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

package/template/tools/scaffold/templates/feature/model.ts

@@ -0,0 +1,142 @@
+import { z } from 'zod'
+import { ApiError } from '@/api'
+import type {
+  ITemplateRecord,
+  ITemplateRecordDto,
+  ITemplateRecordListInput,
+  ITemplateRecordPage,
+  ITemplateRecordPageDto,
+  ITemplateRecordUpdateInput,
+} from './types'
+
+const objTemplateRecordDtoSchema = z.object({
+  enabled: z.boolean(),
+  id: z.string().trim().min(1),
+  name: z.string().trim().min(1),
+  revision: z.number().int().nonnegative(),
+})
+
+const objTemplateRecordPageDtoSchema = z.object({
+  items: z.array(objTemplateRecordDtoSchema),
+  total: z.number().int().nonnegative(),
+})
+
+const objTemplateRecordSchema = z.object({
+  bIsEnabled: z.boolean(),
+  nRevision: z.number().int().nonnegative(),
+  strId: z.string().trim().min(1),
+  strName: z.string().trim().min(1),
+})
+
+const objTemplateRecordListInputSchema = z.object({
+  nPage: z.number().int().min(1),
+  nPageSize: z.number().int().min(1).max(100),
+  strKeyword: z.string().trim().min(1).optional(),
+})
+
+const objTemplateRecordUpdateInputSchema = z.object({
+  nExpectedRevision: z.number().int().nonnegative(),
+  objChanges: z
+    .object({
+      bIsEnabled: z.boolean().optional(),
+      strName: z.string().trim().min(1).optional(),
+    })
+    .refine(
+      (objChanges) =>
+        objChanges.bIsEnabled !== undefined || objChanges.strName !== undefined,
+      '至少需要修改一个字段。'
+    ),
+  strRecordId: z.string().trim().min(1),
+})
+
+function fnCreateInvalidTemplateResponseError(strResource: string) {
+  return new ApiError({
+    bRetriable: false,
+    strCode: 'TEMPLATE_INVALID_RESPONSE',
+    strKind: 'invalid_response',
+    strMessage: `${strResource}接口返回了不符合 Feature 契约的数据。`,
+  })
+}
+
+/** 规范化记录标识，确保 Query Key 与 Repository 请求使用同一个值。 */
+export function fnNormalizeTemplateRecordId(strRecordId: string) {
+  const objResult = z.string().trim().min(1).safeParse(strRecordId)
+  if (!objResult.success) {
+    throw new TypeError('记录标识不能为空。')
+  }
+  return objResult.data
+}
+
+/** 校验并将生成客户端 DTO 映射为 Feature 领域记录。 */
+export function fnMapTemplateRecordDto(
+  objDto: ITemplateRecordDto
+): ITemplateRecord {
+  const objResult = objTemplateRecordDtoSchema.safeParse(objDto)
+  if (!objResult.success) {
+    throw fnCreateInvalidTemplateResponseError('记录详情')
+  }
+
+  const objRecord: ITemplateRecord = {
+    bIsEnabled: objResult.data.enabled,
+    nRevision: objResult.data.revision,
+    strId: objResult.data.id,
+    strName: objResult.data.name,
+  }
+  return Object.freeze(objRecord)
+}
+
+/** 校验并将生成客户端分页 DTO 映射为 Feature 领域分页结果。 */
+export function fnMapTemplateRecordPageDto(
+  objDto: ITemplateRecordPageDto
+): ITemplateRecordPage {
+  const objResult = objTemplateRecordPageDtoSchema.safeParse(objDto)
+  if (!objResult.success) {
+    throw fnCreateInvalidTemplateResponseError('记录列表')
+  }
+
+  const arrRecords = objResult.data.items.map(fnMapTemplateRecordDto)
+  return Object.freeze({
+    arrRecords: Object.freeze(arrRecords),
+    nTotal: objResult.data.total,
+  })
+}
+
+/** 校验并冻结 Demo Adapter 的领域记录。 */
+export function fnNormalizeTemplateRecord(
+  objRecord: ITemplateRecord
+): ITemplateRecord {
+  const objResult = objTemplateRecordSchema.safeParse(objRecord)
+  if (!objResult.success) {
+    throw new TypeError('Demo 记录必须包含有效标识、名称、状态和版本。')
+  }
+  return Object.freeze(objResult.data)
+}
+
+/** 规范化列表分页与空白关键字。 */
+export function fnNormalizeTemplateRecordListInput(
+  objInput: ITemplateRecordListInput
+): ITemplateRecordListInput {
+  const strKeyword = objInput.strKeyword?.trim() || undefined
+  const objResult = objTemplateRecordListInputSchema.safeParse({
+    ...objInput,
+    strKeyword,
+  })
+  if (!objResult.success) {
+    throw new TypeError('列表页码必须有效，且每页记录数必须在 1 到 100 之间。')
+  }
+  return Object.freeze(objResult.data)
+}
+
+/** 规范化更新命令并确保至少修改一个字段。 */
+export function fnNormalizeTemplateRecordUpdateInput(
+  objInput: ITemplateRecordUpdateInput
+): ITemplateRecordUpdateInput {
+  const objResult = objTemplateRecordUpdateInputSchema.safeParse(objInput)
+  if (!objResult.success) {
+    throw new TypeError('更新命令必须包含有效记录、版本和至少一个修改字段。')
+  }
+  return Object.freeze({
+    ...objResult.data,
+    objChanges: Object.freeze(objResult.data.objChanges),
+  })
+}

package/template/tools/scaffold/templates/feature/queries.ts

@@ -0,0 +1,154 @@
+import { useMemo } from 'react'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import {
+  fnApplyOptimisticQueryUpdate,
+  fnCreateAppMutationScope,
+  fnCreateAppQueryKeys,
+  fnRollbackOptimisticQueryUpdate,
+  useAppQueryScope,
+  type IAppQueryRollbackSnapshot,
+} from '@/api/query'
+import {
+  fnNormalizeTemplateRecordId,
+  fnNormalizeTemplateRecordListInput,
+  fnNormalizeTemplateRecordUpdateInput,
+} from './model'
+import { fnResolveTemplateRecordFeature } from './repository'
+import type {
+  ITemplateRecord,
+  ITemplateRecordUpdateCommand,
+  IUseTemplateRecordDetailOptions,
+  IUseTemplateRecordListOptions,
+  IUseUpdateTemplateRecordOptions,
+} from './types'
+
+const strFeatureKey = 'featureTemplate'
+const strRecordResourceKey = 'records'
+
+function useTemplateRecordKeys(strWorkspaceId: string | undefined) {
+  const objScope = useAppQueryScope({ strWorkspaceId })
+  return useMemo(
+    () => fnCreateAppQueryKeys(strFeatureKey, objScope),
+    [objScope]
+  )
+}
+
+/** 使用统一作用域读取中性记录列表，最终授权由后端负责。 */
+export function useTemplateRecordList({
+  objInput,
+  objFeature,
+  strWorkspaceId,
+}: IUseTemplateRecordListOptions) {
+  const { objRepository } = fnResolveTemplateRecordFeature(objFeature)
+  const objKeys = useTemplateRecordKeys(strWorkspaceId)
+  const { nPage, nPageSize, strKeyword } = objInput
+  const objNormalizedInput = useMemo(
+    () =>
+      fnNormalizeTemplateRecordListInput({
+        nPage,
+        nPageSize,
+        strKeyword,
+      }),
+    [nPage, nPageSize, strKeyword]
+  )
+
+  return useQuery({
+    queryKey: objKeys.fnList(strRecordResourceKey, {
+      nPage: objNormalizedInput.nPage,
+      nPageSize: objNormalizedInput.nPageSize,
+      ...(objNormalizedInput.strKeyword
+        ? { strKeyword: objNormalizedInput.strKeyword }
+        : {}),
+    }),
+    queryFn: ({ signal: objSignal }) =>
+      objRepository.fnList(objNormalizedInput, objSignal),
+  })
+}
+
+/** 使用统一作用域读取一条中性记录详情，最终授权由后端负责。 */
+export function useTemplateRecordDetail({
+  objFeature,
+  strRecordId,
+  strWorkspaceId,
+}: IUseTemplateRecordDetailOptions) {
+  const { objRepository } = fnResolveTemplateRecordFeature(objFeature)
+  const objKeys = useTemplateRecordKeys(strWorkspaceId)
+  const strNormalizedRecordId = fnNormalizeTemplateRecordId(strRecordId)
+
+  return useQuery({
+    queryKey: objKeys.fnDetail(strRecordResourceKey, strNormalizedRecordId),
+    queryFn: ({ signal: objSignal }) =>
+      objRepository.fnGet(strNormalizedRecordId, objSignal),
+  })
+}
+
+/** 更新一条记录，并演示详情乐观回滚、串行写入和列表失效。 */
+export function useUpdateTemplateRecord({
+  objFeature,
+  strRecordId,
+  strWorkspaceId,
+}: IUseUpdateTemplateRecordOptions) {
+  const { objRepository } = fnResolveTemplateRecordFeature(objFeature)
+  const objQueryClient = useQueryClient()
+  const objKeys = useTemplateRecordKeys(strWorkspaceId)
+  const strNormalizedRecordId = fnNormalizeTemplateRecordId(strRecordId)
+  const arrDetailKey = objKeys.fnDetail(
+    strRecordResourceKey,
+    strNormalizedRecordId
+  )
+
+  return useMutation<
+    ITemplateRecord,
+    Error,
+    ITemplateRecordUpdateCommand,
+    IAppQueryRollbackSnapshot<ITemplateRecord> | null
+  >({
+    mutationFn: (objCommand: ITemplateRecordUpdateCommand) =>
+      objRepository.fnUpdate(
+        fnNormalizeTemplateRecordUpdateInput({
+          ...objCommand,
+          strRecordId: strNormalizedRecordId,
+        })
+      ),
+    scope: fnCreateAppMutationScope(arrDetailKey),
+    onMutate: async (objCommand) => {
+      const objCurrentRecord =
+        objQueryClient.getQueryData<ITemplateRecord>(arrDetailKey)
+      if (!objCurrentRecord) return null
+
+      const objNormalizedInput = fnNormalizeTemplateRecordUpdateInput({
+        ...objCommand,
+        strRecordId: strNormalizedRecordId,
+      })
+      return fnApplyOptimisticQueryUpdate<ITemplateRecord>(
+        objQueryClient,
+        arrDetailKey,
+        (objRecord) =>
+          Object.freeze({
+            ...(objRecord ?? objCurrentRecord),
+            ...objNormalizedInput.objChanges,
+            nRevision: objNormalizedInput.nExpectedRevision + 1,
+          })
+      )
+    },
+    onError: (_objError, _objCommand, objSnapshot) => {
+      if (objSnapshot) {
+        fnRollbackOptimisticQueryUpdate(objQueryClient, objSnapshot)
+      }
+    },
+    onSuccess: (objRecord) => {
+      objQueryClient.setQueryData(arrDetailKey, objRecord)
+    },
+    onSettled: async () => {
+      await Promise.all([
+        objQueryClient.invalidateQueries({
+          exact: true,
+          queryKey: arrDetailKey,
+        }),
+        objQueryClient.invalidateQueries({
+          queryKey: objKeys.fnLists(strRecordResourceKey),
+        }),
+      ])
+    },
+  })
+}

package/template/tools/scaffold/templates/feature/repository.ts

@@ -0,0 +1,206 @@
+import { ApiError } from '@/api'
+import {
+  fnMapTemplateRecordDto,
+  fnMapTemplateRecordPageDto,
+  fnNormalizeTemplateRecord,
+  fnNormalizeTemplateRecordId,
+  fnNormalizeTemplateRecordListInput,
+  fnNormalizeTemplateRecordUpdateInput,
+} from './model'
+import {
+  objTemplateRecordFeatureBrand,
+  type IConnectedTemplateRecordSource,
+  type ICreateTemplateRecordFeatureOptions,
+  type ICreateTemplateRecordRepositoryOptions,
+  type ITemplateRecord,
+  type ITemplateRecordFeature,
+  type ITemplateRecordRepository,
+} from './types'
+
+const arrDefaultDemoRecords: readonly ITemplateRecord[] = Object.freeze([
+  Object.freeze({
+    bIsEnabled: true,
+    nRevision: 0,
+    strId: 'record-1',
+    strName: '示例记录',
+  }),
+])
+
+function fnCreateTemplateRecordNotFoundError(strRecordId: string) {
+  return new ApiError({
+    bRetriable: false,
+    nStatus: 404,
+    strCode: 'TEMPLATE_RECORD_NOT_FOUND',
+    strKind: 'http',
+    strMessage: `未找到记录 ${strRecordId}。`,
+  })
+}
+
+function fnCreateTemplateRecordConflictError(strRecordId: string) {
+  return new ApiError({
+    bRetriable: false,
+    nStatus: 409,
+    strCode: 'TEMPLATE_RECORD_CONFLICT',
+    strKind: 'http',
+    strMessage: `记录 ${strRecordId} 已被其他操作更新，请刷新后重试。`,
+  })
+}
+
+function fnCreateDemoTemplateRecordRepository(
+  arrInitialRecords: readonly ITemplateRecord[]
+): ITemplateRecordRepository {
+  let arrRecords = arrInitialRecords.map(fnNormalizeTemplateRecord)
+
+  const objRepository: ITemplateRecordRepository = {
+    fnGet: async (strRecordId, objSignal) => {
+      objSignal.throwIfAborted()
+      const strNormalizedRecordId = fnNormalizeTemplateRecordId(strRecordId)
+      const objRecord = arrRecords.find(
+        (objCandidate) => objCandidate.strId === strNormalizedRecordId
+      )
+      if (!objRecord) {
+        throw fnCreateTemplateRecordNotFoundError(strNormalizedRecordId)
+      }
+      return objRecord
+    },
+    fnList: async (objInput, objSignal) => {
+      objSignal.throwIfAborted()
+      const objNormalizedInput = fnNormalizeTemplateRecordListInput(objInput)
+      const strKeyword = objNormalizedInput.strKeyword?.toLocaleLowerCase()
+      const arrFilteredRecords = strKeyword
+        ? arrRecords.filter((objRecord) =>
+            objRecord.strName.toLocaleLowerCase().includes(strKeyword)
+          )
+        : arrRecords
+      const nStart =
+        (objNormalizedInput.nPage - 1) * objNormalizedInput.nPageSize
+      return Object.freeze({
+        arrRecords: Object.freeze(
+          arrFilteredRecords.slice(
+            nStart,
+            nStart + objNormalizedInput.nPageSize
+          )
+        ),
+        nTotal: arrFilteredRecords.length,
+      })
+    },
+    fnUpdate: async (objInput) => {
+      const objNormalizedInput = fnNormalizeTemplateRecordUpdateInput(objInput)
+      const nRecordIndex = arrRecords.findIndex(
+        (objRecord) => objRecord.strId === objNormalizedInput.strRecordId
+      )
+      const objCurrentRecord = arrRecords[nRecordIndex]
+      if (!objCurrentRecord) {
+        throw fnCreateTemplateRecordNotFoundError(
+          objNormalizedInput.strRecordId
+        )
+      }
+      if (objCurrentRecord.nRevision !== objNormalizedInput.nExpectedRevision) {
+        throw fnCreateTemplateRecordConflictError(
+          objNormalizedInput.strRecordId
+        )
+      }
+
+      const objUpdatedRecord = fnNormalizeTemplateRecord({
+        ...objCurrentRecord,
+        ...objNormalizedInput.objChanges,
+        nRevision: objCurrentRecord.nRevision + 1,
+      })
+      arrRecords = arrRecords.map((objRecord, nIndex) =>
+        nIndex === nRecordIndex ? objUpdatedRecord : objRecord
+      )
+      return objUpdatedRecord
+    },
+  }
+  return Object.freeze(objRepository)
+}
+
+function fnCreateConnectedTemplateRecordRepository(
+  objSource: IConnectedTemplateRecordSource
+): ITemplateRecordRepository {
+  const objRepository: ITemplateRecordRepository = {
+    fnGet: async (strRecordId, objSignal) =>
+      fnMapTemplateRecordDto(
+        await objSource.fnGet(
+          fnNormalizeTemplateRecordId(strRecordId),
+          objSignal
+        )
+      ),
+    fnList: async (objInput, objSignal) =>
+      fnMapTemplateRecordPageDto(
+        await objSource.fnList(
+          fnNormalizeTemplateRecordListInput(objInput),
+          objSignal
+        )
+      ),
+    fnUpdate: async (objInput) =>
+      fnMapTemplateRecordDto(
+        await objSource.fnUpdate(fnNormalizeTemplateRecordUpdateInput(objInput))
+      ),
+  }
+  return Object.freeze(objRepository)
+}
+
+/** 按运行时模式选择 Demo 或 Connected Adapter，不允许静默回退。 */
+function fnCreateTemplateRecordRepository({
+  arrDemoRecords = arrDefaultDemoRecords,
+  objConnectedSource,
+  strMode,
+}: ICreateTemplateRecordRepositoryOptions): ITemplateRecordRepository {
+  if (strMode === 'demo') {
+    return fnCreateDemoTemplateRecordRepository(arrDemoRecords)
+  }
+  if (!objConnectedSource) {
+    throw new TypeError('Connected 模式必须配置 Swagger 生成客户端数据源。')
+  }
+  return fnCreateConnectedTemplateRecordRepository(objConnectedSource)
+}
+
+class TemplateRecordFeature implements ITemplateRecordFeature {
+  readonly [objTemplateRecordFeatureBrand] = () => undefined
+
+  constructor(
+    readonly objRepository: ITemplateRecordRepository,
+    readonly strReadPermission: string,
+    readonly strWritePermission: string
+  ) {}
+}
+
+function fnNormalizePermission(strPermission: string, strFieldName: string) {
+  const strNormalizedPermission = strPermission.trim()
+  if (!strNormalizedPermission) {
+    throw new TypeError(`${strFieldName} 不能为空。`)
+  }
+  return strNormalizedPermission
+}
+
+/** 一次性组合数据 Adapter 与权限策略，页面不再重复了解这些细节。 */
+export function fnCreateTemplateRecordFeature({
+  arrDemoRecords,
+  objConnectedSource,
+  strMode,
+  strReadPermission,
+  strWritePermission,
+}: ICreateTemplateRecordFeatureOptions): ITemplateRecordFeature {
+  return Object.freeze(
+    new TemplateRecordFeature(
+      fnCreateTemplateRecordRepository({
+        arrDemoRecords,
+        objConnectedSource,
+        strMode,
+      }),
+      fnNormalizePermission(strReadPermission, 'strReadPermission'),
+      fnNormalizePermission(strWritePermission, 'strWritePermission')
+    )
+  )
+}
+
+/** 仅供 Feature 内部 Query implementation 读取已组合的运行依赖。 */
+export function fnResolveTemplateRecordFeature(
+  objFeature: ITemplateRecordFeature
+) {
+  if (!(objFeature instanceof TemplateRecordFeature)) {
+    throw new TypeError('必须使用 fnCreateTemplateRecordFeature 创建 Feature。')
+  }
+  return objFeature
+}

package/template/tools/scaffold/templates/feature/types.ts

@@ -0,0 +1,168 @@
+/** Swagger 客户端返回的中性记录 DTO；字段名保持后端数据契约。 */
+export interface ITemplateRecordDto {
+  /** 后端生成的稳定实体标识。 */
+  id?: string
+  /** 面向用户展示的记录名称。 */
+  name?: string
+  /** 记录当前是否启用。 */
+  enabled?: boolean
+  /** 服务端并发控制版本。 */
+  revision?: number
+}
+
+/** Swagger 客户端返回的中性记录分页 DTO。 */
+export interface ITemplateRecordPageDto {
+  /** 当前页的原始记录。 */
+  items?: readonly ITemplateRecordDto[]
+  /** 当前筛选条件下的记录总数。 */
+  total?: number
+}
+
+/** Feature 内部使用、与传输格式解耦的中性领域记录。 */
+export interface ITemplateRecord {
+  /** 当前记录是否启用。 */
+  readonly bIsEnabled: boolean
+  /** 服务端并发控制版本。 */
+  readonly nRevision: number
+  /** 稳定实体标识。 */
+  readonly strId: string
+  /** 已去除首尾空白的展示名称。 */
+  readonly strName: string
+}
+
+/** Feature 列表使用的领域分页结果。 */
+export interface ITemplateRecordPage {
+  /** 当前页经过校验和映射的记录。 */
+  readonly arrRecords: readonly ITemplateRecord[]
+  /** 当前筛选条件下的记录总数。 */
+  readonly nTotal: number
+}
+
+/** 中性记录列表查询输入。 */
+export interface ITemplateRecordListInput {
+  /** 从 `1` 开始的页码。 */
+  readonly nPage: number
+  /** 每页记录数，允许 `1` 到 `100`。 */
+  readonly nPageSize: number
+  /** 可选名称关键字；空白文本按未提供处理。 */
+  readonly strKeyword?: string
+}
+
+/** 一次记录更新允许修改的字段。 */
+export interface ITemplateRecordChanges {
+  /** 更新后的启用状态；未提供时保持原值。 */
+  readonly bIsEnabled?: boolean
+  /** 更新后的名称；未提供时保持原值。 */
+  readonly strName?: string
+}
+
+/** UI 触发更新 Mutation 时提交的命令。 */
+export interface ITemplateRecordUpdateCommand {
+  /** 用户开始编辑时读取的服务端版本。 */
+  readonly nExpectedRevision: number
+  /** 本次明确修改的字段，至少包含一项。 */
+  readonly objChanges: ITemplateRecordChanges
+}
+
+/** Repository 接收的完整记录更新输入。 */
+export interface ITemplateRecordUpdateInput extends ITemplateRecordUpdateCommand {
+  /** 需要更新的稳定记录标识。 */
+  readonly strRecordId: string
+}
+
+/** Feature 依赖的最小数据访问契约。 */
+export interface ITemplateRecordRepository {
+  /** 按稳定标识读取详情，并响应 Query 的取消信号。 */
+  readonly fnGet: (
+    strRecordId: string,
+    objSignal: AbortSignal
+  ) => Promise<ITemplateRecord>
+  /** 按筛选和分页条件读取列表，并响应 Query 的取消信号。 */
+  readonly fnList: (
+    objInput: ITemplateRecordListInput,
+    objSignal: AbortSignal
+  ) => Promise<ITemplateRecordPage>
+  /** 更新一条记录；服务端负责最终版本检查和授权。 */
+  readonly fnUpdate: (
+    objInput: ITemplateRecordUpdateInput
+  ) => Promise<ITemplateRecord>
+}
+
+/** Connected Adapter 由 Swagger 生成客户端实现的数据源。 */
+export interface IConnectedTemplateRecordSource {
+  /** 调用生成客户端的详情接口并原样返回 DTO。 */
+  readonly fnGet: (
+    strRecordId: string,
+    objSignal: AbortSignal
+  ) => Promise<ITemplateRecordDto>
+  /** 调用生成客户端的列表接口并原样返回分页 DTO。 */
+  readonly fnList: (
+    objInput: ITemplateRecordListInput,
+    objSignal: AbortSignal
+  ) => Promise<ITemplateRecordPageDto>
+  /** 调用生成客户端的更新接口并返回服务端最终 DTO。 */
+  readonly fnUpdate: (
+    objInput: ITemplateRecordUpdateInput
+  ) => Promise<ITemplateRecordDto>
+}
+
+/** 根据运行模式创建中性 Feature Repository 的配置。 */
+export interface ICreateTemplateRecordRepositoryOptions {
+  /** Demo Adapter 的初始领域记录；省略时使用中性示例数据。 */
+  readonly arrDemoRecords?: readonly ITemplateRecord[]
+  /** Connected 模式必填的生成客户端数据源。 */
+  readonly objConnectedSource?: IConnectedTemplateRecordSource
+  /** 与应用运行时配置一致的数据模式。 */
+  readonly strMode: 'connected' | 'demo'
+}
+
+/** 由 Feature 组合点创建、页面只能透传的不可伪造运行实例标记。 */
+export const objTemplateRecordFeatureBrand = Symbol('TemplateRecordFeature')
+
+/**
+ * 已完成 Adapter、权限和缓存策略组合的 Feature 运行实例。
+ *
+ * 页面只持有并传递该实例，不读取 Repository 或权限配置。
+ */
+export interface ITemplateRecordFeature {
+  /** 阻止页面用普通对象绕过 Feature 组合点。 */
+  readonly [objTemplateRecordFeatureBrand]: () => void
+}
+
+/** 创建 Feature 运行实例时一次性声明的项目接入配置。 */
+export interface ICreateTemplateRecordFeatureOptions extends ICreateTemplateRecordRepositoryOptions {
+  /** 列表和详情读取使用的稳定权限码。 */
+  readonly strReadPermission: string
+  /** 更新记录使用的稳定权限码。 */
+  readonly strWritePermission: string
+}
+
+/** 中性记录列表 Query Hook 的配置。 */
+export interface IUseTemplateRecordListOptions {
+  /** 当前分页和筛选条件。 */
+  readonly objInput: ITemplateRecordListInput
+  /** 应用组合点创建的 Feature 运行实例。 */
+  readonly objFeature: ITemplateRecordFeature
+  /** 可选的组织、项目或工作空间二级缓存作用域。 */
+  readonly strWorkspaceId?: string
+}
+
+/** 中性记录详情 Query Hook 的配置。 */
+export interface IUseTemplateRecordDetailOptions {
+  /** 应用组合点创建的 Feature 运行实例。 */
+  readonly objFeature: ITemplateRecordFeature
+  /** 需要读取的稳定记录标识。 */
+  readonly strRecordId: string
+  /** 可选的组织、项目或工作空间二级缓存作用域。 */
+  readonly strWorkspaceId?: string
+}
+
+/** 中性记录更新 Mutation Hook 的配置。 */
+export interface IUseUpdateTemplateRecordOptions {
+  /** 应用组合点创建的 Feature 运行实例。 */
+  readonly objFeature: ITemplateRecordFeature
+  /** 需要更新的稳定记录标识。 */
+  readonly strRecordId: string
+  /** 可选的组织、项目或工作空间二级缓存作用域。 */
+  readonly strWorkspaceId?: string
+}