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

package/template/docs/file-capabilities.md

@@ -0,0 +1,196 @@
+# 文件能力接入指南
+
+`src/files` 提供上传、下载和导入/导出任务的公共状态与安全边界；
+`FileUpload` 提供核心上传交互，`filePreview` 能力完整提供 `FilePreview`、预览类型和适配器。基础层不包含接口地址、OSS/S3 SDK、
+Office 服务地址或具体导入模板，所有网络请求都由 Feature 使用
+`swagger-typescript-api` 生成客户端适配。
+
+## 安全与职责
+
+- 文件名、扩展名、浏览器 MIME、响应头和外部预览 URL 都是不可信输入。
+- 浏览器大小/MIME 校验只用于尽早反馈；后端必须重新鉴权、限制大小、识别真实内容、
+  扫描恶意文件，并返回标准 `ApiError`。
+- 上传/下载适配器必须把 `objSignal` 传给生成客户端，把 Axios 进度事件转换为
+  `IFileTransferProgress`。取消信号被忽略时，基础层无法强制终止网络流量。
+- 图片只内建 AVIF/GIF/JPEG/PNG/WebP，主动排除 SVG；PDF 和外部预览放在沙箱
+  iframe 中。Office 文件交给第三方前必须完成数据合规评审。
+- Blob 下载默认上限为 100 MiB。更大的文件必须在请求前选择流式/签名 URL Adapter，
+  或使用异步导出任务，不能先把整个文件装入浏览器内存。
+- 对象 URL 在保存或预览卸载后统一回收；业务层不要持久化 Blob URL。
+
+## 上传
+
+`FileUpload` 复用全局 `Button` 和 `Input`，支持单/多文件、体验校验、进度、取消与重试。
+组件不引入第二套 UI primitives。
+
+```tsx
+import { FileUpload } from '@/components/FileUpload'
+
+<FileUpload
+  bMultiple
+  objValidation={{
+    arrAcceptedExtensions: ['.pdf', '.docx'],
+    arrAcceptedMimeTypes: [
+      'application/pdf',
+      'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    ],
+    nMaxBytes: 20 * 1024 * 1024,
+    nMaxFiles: 5,
+  }}
+  fnUpload={async ({ arrFiles, fnOnProgress, objSignal }) => {
+    const objFormData = new FormData()
+    arrFiles.forEach((objFile) => objFormData.append('files', objFile))
+    const objResponse = await objDocumentApi.api.documentsUploadCreate(
+      objFormData,
+      {
+        signal: objSignal,
+        onUploadProgress: ({ loaded: nLoaded, total: nTotal }) =>
+          fnOnProgress({
+            nLoadedBytes: nLoaded,
+            nTotalBytes: nTotal,
+            nPercent: nTotal ? Math.round((nLoaded / nTotal) * 100) : undefined,
+          }),
+      }
+    )
+    return objResponse.data
+  }}
+/>
+```
+
+`AppPageForm` 已内建 `type: 'file'`，直接复用同一份全局 `FileUpload`。`fnUpload`
+必须返回最终写入表单字段的文件 ID、对象 Key 或稳定 DTO；生成客户端的原始响应应当在
+Feature Adapter 内完成映射，基础表单不会猜测后端协议。上传成功会进入 PageForm 的
+dirty 生命周期，重置或外部模型替换会卸载当前上传状态并取消仍在执行的请求。
+
+```tsx
+import {
+  AppPageForm,
+  type IFormProp,
+} from '@/components/AppPageForm'
+
+const objFormConfig: IFormProp<IDocumentForm> = {
+  formItems: [
+    {
+      label: '合同附件',
+      prop: 'objAttachment',
+      type: 'file',
+      required: true,
+      fileConfig: {
+        objValidation: {
+          arrAcceptedExtensions: ['.pdf'],
+          nMaxBytes: 20 * 1024 * 1024,
+          nMaxFiles: 1,
+        },
+        fnUpload: async ({ arrFiles, objSignal }) => {
+          const objResponse = await objDocumentApi.api.documentsUploadCreate(
+            fnCreateDocumentFormData(arrFiles),
+            { signal: objSignal }
+          )
+          return {
+            strFileId: objResponse.data.id,
+            strFileName: objResponse.data.name,
+          }
+        },
+      },
+    },
+  ],
+}
+
+<AppPageForm model={objModel} config={objFormConfig} />
+```
+
+已有附件展示、删除、预览或分片上传等复杂交互仍使用自定义 renderer 组合文件能力层，
+不要把业务 DTO 或对象存储协议下沉到 PageForm。
+
+## 下载
+
+中小文件使用 `fnDownloadFile`。它会透传取消/进度、解析并清理
+`Content-Disposition` 文件名，拒绝 JSON/problem+json/HTML 错误 Blob，并在保存后回收
+对象 URL。
+
+```ts
+await fnDownloadFile(
+  {
+    strFallbackFileName: 'document.pdf',
+    fnRequest: async ({ fnOnProgress, objSignal }) => {
+      const objResponse = await objDocumentApi.api.documentsDownloadDetail(
+        strDocumentId,
+        {
+          signal: objSignal,
+          responseType: 'blob',
+          onDownloadProgress: ({ loaded: nLoaded, total: nTotal }) =>
+            fnOnProgress({ nLoadedBytes: nLoaded, nTotalBytes: nTotal }),
+        }
+      )
+      return {
+        objBlob: objResponse.data,
+        strContentDisposition: objResponse.headers['content-disposition'],
+        strContentType: objResponse.headers['content-type'],
+      }
+    },
+  },
+  objAbortController.signal
+)
+```
+
+大文件使用 `fnRunExternalFileDownload` 注入项目 Adapter。Adapter 可以换取短期签名 URL、
+调用受控的 File System Access/流式保存方案，或启动后端异步任务；它必须自行约束 URL
+协议、Origin、凭据和过期时间。
+
+跨域下载若需要读取文件名，服务端还必须暴露响应头：
+
+```http
+Access-Control-Expose-Headers: Content-Disposition, Content-Type, X-Request-ID
+```
+
+## 预览
+
+`FilePreview` 直接支持图片与 PDF。Office 等格式通过 `IFilePreviewAdapter` 接入，默认只
+接受当前站点 Origin；使用外部服务时必须显式传入 `arrAllowedOrigins`。
+
+```bash
+pnpm scaffold:add --target <项目目录> --capability filePreview
+```
+
+```tsx
+<FilePreview
+  objBlob={objFileBlob}
+  strFileName='合同.docx'
+  arrAdapters={[objOfficePreviewAdapter]}
+  arrAllowedOrigins={['https://preview.corp.example']}
+/>
+```
+
+Adapter 创建的临时 URL、上传副本或会话由其 `fnDispose` 回收。基础层不会内置某个
+Office/OSS 供应商，也不会默认把企业文件发送到公网预览服务。
+
+## 导入与导出任务
+
+`useFileTask` 用同一个互斥状态处理立即完成与后台任务：`starting`、`queued`、`running`、
+`success`、`error`、`canceled`。同步导出可在 `fnStart` 中调用 `fnDownloadFile` 后返回
+`completed`；异步导出返回任务 ID，并通过 `fnPoll` 查询到成功后再下载结果。导入同样
+可以把上传后的校验任务映射到该契约。
+
+```tsx
+const objExportTask = useFileTask({
+  objAdapter: {
+    async fnStart(objFilters, objContext) {
+      const objResponse = await objInventoryApi.api.exportsCreate(objFilters, {
+        signal: objContext.objSignal,
+      })
+      return objResponse.data.completed
+        ? { strMode: 'completed', objResult: objResponse.data }
+        : { strMode: 'background', strTaskId: objResponse.data.taskId }
+    },
+    async fnPoll(strTaskId, objContext) {
+      const objResponse = await objInventoryApi.api.exportsDetail(strTaskId, {
+        signal: objContext.objSignal,
+      })
+      return fnMapProjectExportStatus(objResponse.data)
+    },
+  },
+})
+```
+
+具体 CSV/Excel 字段、导入模板、错误明细页面和业务状态映射属于 Feature。脚手架只提供
+生命周期、取消、重试和进度契约。入口显隐由 Feature 权限控制，接口授权由后端完成。

package/template/docs/locale-and-i18n.md

@@ -0,0 +1,132 @@
+# Locale、时区与国际化接入指南
+
+`src/locale` 是应用语言、时区、Intl 格式化和共享文案的唯一基础能力入口。应用组合层把
+同一个 `strLocale` 同时交给 `LocaleProvider`、枚举目录和全局参数目录，避免界面已经切换
+语言但后端元数据仍使用旧语言。
+
+## 运行时配置
+
+部署环境通过 `public/runtime-config.json` 声明默认值：
+
+```json
+{
+  "locale": {
+    "strLocale": "zh-CN",
+    "strTimeZone": "Asia/Shanghai"
+  }
+}
+```
+
+当前脚手架内建 `zh-CN` 和 `en-US`。时区必须是浏览器 Intl 支持的 IANA 名称。缺少
+`locale` 时为旧配置提供 `zh-CN`、`Asia/Shanghai` 兼容默认值；非法语言或时区会在应用
+启动前被拒绝。
+
+`strLocale` 决定共享文案、数字格式和排序规则，`strTimeZone` 决定日期、时间和日期时间
+落在哪个业务时区。用户浏览器时区不会静默覆盖部署配置。
+
+## React 中格式化
+
+```tsx
+import { useLocale } from '@/locale'
+
+function InvoiceAmount({ nAmount, nCreatedAt }: IInvoiceAmountProps) {
+  const objLocale = useLocale()
+
+  return (
+    <div>
+      <span>{objLocale.fnFormatCurrency(nAmount, 'CNY')}</span>
+      <time dateTime={new Date(nCreatedAt).toISOString()}>
+        {objLocale.fnFormatDateTime(nCreatedAt)}
+      </time>
+    </div>
+  )
+}
+```
+
+内建能力包括日期、时间、日期时间、数字、百分比、货币和本地化字符串比较。百分比遵循
+Intl 语义，`0.125` 显示为约 `13%`；货币必须显式提供 ISO 4217 代码。日期输入只接受
+`Date` 或毫秒时间戳，Feature 必须先按后端契约解析字符串，避免无时区字符串被浏览器按
+本地规则猜测。
+
+React 外使用 `fnCreateLocaleFormatter`，不要直接散落 `toLocaleString()`：
+
+```ts
+const objFormatter = fnCreateLocaleFormatter({
+  strLocale: 'zh-CN',
+  strTimeZone: 'Asia/Shanghai',
+})
+
+objFormatter.fnFormatNumber(12_345.67)
+```
+
+无效日期、`NaN` 和无限数字统一显示 `-`。格式化器会在自己的生命周期内复用 Intl 实例。
+
+## Feature 自有语言包
+
+业务文案归所属 Feature 管理，不注册到一个不断膨胀的全局对象，也不由共享组件引用：
+
+```tsx
+// src/features/inventory/messages.ts
+export const objInventoryMessages = fnDefineLocaleMessages({
+  'en-US': {
+    emptyTitle: 'No inventory records',
+    pageTitle: 'Inventory',
+  },
+  'zh-CN': {
+    emptyTitle: '暂无库存记录',
+    pageTitle: '库存管理',
+  },
+})
+
+// Feature 内部组件
+const objMessages = useLocaleMessages(objInventoryMessages)
+const strTitle = objMessages.fnTranslate('pageTitle')
+```
+
+`fnDefineLocaleMessages` 要求每个 Key 在所有内建语言中都存在，漏翻译会在 TypeScript
+阶段暴露。语言包随 Feature 路由分包，不需要在 `Application` 注册。
+
+## 共享文案
+
+壳层和基础组件使用稳定的 `TSharedMessageKey`。项目确需修改通用文案时，通过
+`Application.objLocale.objSharedMessages` 按语言覆盖；不要修改组件内部或把业务文案放进共享目录：
+
+```tsx
+<Application
+  objLocale={{
+    strLocale: 'en-US',
+    strTimeZone: 'UTC',
+    objSharedMessages: {
+      'en-US': { 'common.retry': 'Try again' },
+    },
+  }}
+/>
+```
+
+当前已迁移登录、首页、错误页、路由导航元数据、文件上传/预览、普通数据表、JSON 编辑器、
+密码输入、Header 搜索、主题、用户菜单和 `AppDialog`。调用方显式传入的按钮、标题和内容
+始终优先于共享默认文案。
+
+`AppPageForm` 和 `AppTable` 的文案数量较多，并包含参数化校验错误，因此各自在组件目录
+维护完整的强类型消息合同。两者默认跟随 `LocaleProvider`，同时允许通过组件的
+`messages` 属性做实例级局部覆盖：
+
+```tsx
+<AppTable
+  tableKey='orders'
+  messages={{ strSearch: '查找订单' }}
+  config={objOrderTableConfig}
+/>
+```
+
+`AppTable` 的 React 控件、纯 DOM renderer、解析/校验和保存结算使用同一份消息对象，避免
+出现界面已经切换语言而单元格错误仍为另一种语言。纯 engine 被 React 外直接调用时保留
+中文兼容默认值；独立消费者可显式传入 `TableEngineMessages`。PageForm 的显式业务校验
+消息仍优先，只有内建 required、长度、格式等默认错误由组件语言合同生成。
+
+## 语言切换所有权
+
+`LocaleProvider` 是受控 Provider，不自己持久化用户选择。项目需要语言切换时，由应用
+组合层或用户偏好 Feature 持有 `strLocale`，再传给 `Application`；切换后 Provider、HTML
+`lang`、Intl 和元数据 Query 会一起更新。浏览器存储、服务端用户偏好及权限由具体项目
+决定，基础层不建立第二份 Locale Store。

package/template/docs/mutation-idempotency.md

@@ -0,0 +1,24 @@
+# Mutation 幂等约定
+
+写操作的最终幂等由后端按用户意图和幂等键原子执行。前端只负责为需要幂等的请求创建
+键，并通过统一 Axios Hook 写入 `Idempotency-Key` Header；不要在浏览器中维护另一套事务
+确认状态机。
+
+```ts
+const strIdempotencyKey = fnCreateIdempotencyKey()
+
+await objGeneratedApi.records.updateRecord(strRecordId, objBody, {
+  strIdempotencyKey,
+})
+```
+
+同一次用户操作在手动重试时复用原键；新的用户意图创建新键。后端必须校验请求指纹、
+授权与租户，并返回第一次执行的稳定结果。网络结果不明确时，页面应按具体业务接口查询
+最新服务端事实，而不是由通用前端控制器推断事务结果。
+
+公共入口 `@/api/idempotency` 仅导出：
+
+- `fnCreateIdempotencyKey()`：使用浏览器 `crypto.randomUUID()` 创建键；
+- `fnNormalizeIdempotencyKey()`：拒绝不能安全写入 HTTP Header 的值。
+
+请求头映射契约由 `tests/unit/api/hooks/request.test.ts` 验证。

package/template/docs/optional-editors.md

@@ -0,0 +1,203 @@
+# 地图、富文本和图形编辑器接入
+
+`src/optionalEditors` 提供地图、富文本和图形编辑器共享的运行时边界：专用容器挂载、
+权限体验预检、SDK 生命周期、竞态取消、dirty 状态、结构化文档导出和项目版本迁移。
+它不内置地图/编辑器供应商，也不试图统一三类文档的业务语义。
+
+现有 `JsonEditor` 是一个独立的 JSON 源文本控件，继续按需用于配置编辑；它不是富文本
+或图形编辑器 Adapter，也不会被本模块重新包装。
+
+## 统一与不统一的边界
+
+| 能力         | 脚手架统一                           | 项目 Adapter 或 Feature 负责                     |
+| ------------ | ------------------------------------ | ------------------------------------------------ |
+| SDK 生命周期 | 挂载、取消、最后请求生效、退订和销毁 | 动态加载具体 SDK、Worker、插件和样式             |
+| 文档身份     | ID、能力分类、结构版本、可选内容修订 | 具体 GeoJSON、富文本树或图形节点契约             |
+| 运行时校验   | 信封、类型匹配、模式、事件和迁移路径 | 文档节点、属性、大小、URL 和供应商数据校验       |
+| dirty 与保存 | dirty 快照和 `fnMarkSaved`           | 保存接口、并发控制、冲突处理、服务端最终授权     |
+| DOM          | 只提供一个专用空容器                 | 编辑器内部 DOM/Canvas/WebGL 及无障碍行为         |
+| 内容展示     | 不提供 HTML sink                     | 安全只读渲染、文本替代、静态预览或受控 sanitizer |
+| 版本迁移     | 唯一线性路径、循环检测、逐步校验     | 每个版本的纯数据转换和发布/回滚策略              |
+
+不要建立一个同时理解地图图层、富文本节点和流程图连线的“万能编辑器模型”。稳定复用的是
+资源生命周期和文档信封，不是供应商命令、工具栏或业务结构。
+
+## 文档信封
+
+业务接口返回项目拥有的结构化文档，而不是供应商实例、DOM、Canvas 或 HTML 字符串：
+
+```ts
+interface IArticleDocument {
+  readonly arrContent: readonly IArticleNode[]
+  readonly strDocumentType: 'article'
+}
+
+const objEditorDocument = {
+  objDocument: objArticleQuery.data.document,
+  strContentRevision: objArticleQuery.data.etag,
+  strDocumentId: objArticleQuery.data.id,
+  strEditorKind: 'richText',
+  strSchemaVersion: 'article-v3',
+}
+```
+
+- `strSchemaVersion` 属于项目文档契约，不等于 Tiptap、Lexical、Mapbox 或其他 SDK 版本。
+- `strContentRevision` 表示同一文档的服务端内容版本，可使用 ETag/Revision；变化时 Hook
+  会重建会话。省略时，同 ID、类型和结构版本的普通 React 重渲染不会反复挂载 SDK。
+- `objDocument` 必须是结构化对象，并由 Adapter 的 `fnValidateDocument` 在挂载、迁移和
+  导出后校验。字符串 HTML、供应商实例和循环对象不属于合法标准文档。
+
+后端保存时仍必须验证文档结构、节点数量、字符串长度、资源地址、租户归属和权限，
+并使用 `strContentRevision` 做乐观并发控制。前端类型和 dirty 状态不能替代这些检查。
+
+## Adapter 与路由级挂载
+
+每个项目和编辑器类型实现独立 Adapter。供应商 SDK 必须在 `fnMount` 内动态加载：
+
+```tsx
+import type { IOptionalEditorAdapter } from '@/optionalEditors'
+
+export const objArticleEditorAdapter: IOptionalEditorAdapter<
+  IArticleDocument,
+  IArticleEditorBinding
+> = {
+  strEditorKind: 'richText',
+  fnValidateDocument: fnValidateArticleDocument,
+  async fnMount(objRequest) {
+    const { fnMountArticleEditor } = await import('./vendorArticleEditor')
+    return fnMountArticleEditor({
+      bIsReadOnly: objRequest.strMode === 'view',
+      fnOnAbort: () => objRequest.objSignal.aborted,
+      objContainer: objRequest.objContainer,
+      objDocument: objRequest.objDocument.objDocument,
+    })
+  },
+}
+```
+
+返回的 Session 必须实现：
+
+- `objBinding`：Feature 需要的强类型命令，不暴露无关管理 API。
+- `fnReadDocument`：导出项目结构化文档，不能返回 HTML DOM 或 SDK 实例。
+- `fnSubscribe`：发送完整 dirty 状态或安全致命失败，返回解除监听函数。
+- `fnDestroy`：可重复销毁实例、Worker、Observer、WebGL、对象 URL、事件和专用 DOM。
+
+Adapter 必须响应 `objSignal`。如果 SDK 初始化无法真正取消，迟到 Session 仍会被控制器
+立即销毁。供应商原因码只能使用稳定字符，不得包含正文、Token、URL 或堆栈。
+
+Feature 使用 Hook，并为宿主元素提供可感知名称和明确尺寸：
+
+```tsx
+const objEditor = useOptionalEditor({
+  objAdapter: objArticleEditorAdapter,
+  objDocument: objEditorDocument,
+  strMode: 'edit',
+})
+
+return (
+  <section aria-labelledby='article-editor-title'>
+    <h1 id='article-editor-title'>文章内容</h1>
+    <div
+      ref={objEditor.fnSetContainer}
+      aria-label='文章富文本编辑器'
+      className='min-h-96'
+    />
+  </section>
+)
+```
+
+路由、文档、内容修订、结构版本、身份作用域或 Adapter 变化时会销毁旧会话。模块不装入
+应用根 Provider，也不提供默认页面、路由或菜单。
+
+## 保存与未保存保护
+
+保存时先调用 `fnExportDocument`。它会从当前 Session 读取结构化值，并再次执行项目
+校验；会话在导出过程中被替换会得到稳定错误，不能把迟到结果写回新文档。
+
+```ts
+const objDocument = await objEditor.fnExportDocument()
+await objGeneratedApi.articles.update(
+  objDocument.strDocumentId,
+  {
+    content: objDocument.objDocument,
+    contentRevision: objDocument.strContentRevision,
+    schemaVersion: objDocument.strSchemaVersion,
+  }
+)
+objEditor.fnMarkSaved()
+```
+
+只有后端明确保存成功后才能调用 `fnMarkSaved`。将活动快照的 `bIsDirty` 接入现有
+`UnsavedChangesProvider`；取消请求、自动保存失败、权限撤销或 SDK 崩溃都不能错误清除
+dirty 状态。协同编辑项目可组合 P2-04，但只能由一个项目 Adapter 拥有编辑器和 CRDT
+绑定，不能让两个基础控制器同时创建同一 SDK 实例。
+
+## 项目版本迁移
+
+读取旧文档后，在挂载 SDK 前执行显式、前向、纯数据迁移：
+
+```ts
+const objMigratedDocument = fnMigrateOptionalEditorDocument({
+  objDocument: objResponse.data,
+  strTargetVersion: 'article-v3',
+  fnValidateDocument: fnValidateArticleDocument,
+  arrMigrations: [
+    {
+      strFromVersion: 'article-v1',
+      strToVersion: 'article-v2',
+      fnMigrate: fnMigrateArticleV1ToV2,
+    },
+    {
+      strFromVersion: 'article-v2',
+      strToVersion: 'article-v3',
+      fnMigrate: fnMigrateArticleV2ToV3,
+    },
+  ],
+})
+```
+
+每个来源版本只能有一个下一步，单次最多 20 步；缺失路径、循环、同版本迁移和任一步
+校验失败都会停止。迁移函数不得访问网络、DOM、当前用户或供应商全局状态，必须保证
+同一输入产生同一输出。大规模永久升级由后端批处理并记录审计，浏览器迁移只是兼容
+读取和渐进发布边界。
+
+## 三类编辑器专项要求
+
+### 地图
+
+- 标准文档优先使用项目约束后的 GeoJSON/图层配置对象，限制坐标数、精度和范围。
+- 地址、轨迹、家庭/工作位置可能是个人敏感数据，禁止默认进入日志和遥测。
+- 地理编码、路径规划和受保护图层由后端授权；浏览器不能持有供应商管理密钥。
+- 公开瓦片 Token 必须限制 Origin、配额和能力，并通过运行时配置注入和 Kill Switch 撤销。
+- 审查 CSP `connect-src`、`img-src`、`worker-src`，销毁 WebGL Context、Worker 和监听器。
+- 提供键盘操作、列表/文本替代和非地图查看路径，不能只用颜色或拖拽表达状态。
+
+### 富文本
+
+- 标准存储优先使用项目结构化 JSON；不把编辑器生成 HTML 直接写入
+  `dangerouslySetInnerHTML`。
+- 真正需要 HTML 展示时，在单一边界使用维护中的白名单 sanitizer，并针对链接、图片、
+  iframe、SVG、样式、事件属性和 `javascript:` 协议做攻击回归测试。
+- 图片和附件复用 `src/files` 上传能力，服务端重新校验 MIME、扫描内容和授权文件 ID。
+- 限制粘贴 HTML、超长文档、嵌套深度、提及查询和外部嵌入；不默认允许任意 iframe。
+- 验证标题层级、列表、表格、链接名称、键盘快捷键、焦点和只读模式的语义输出。
+
+### 图形编辑器
+
+- 标准存储使用项目节点/边/画布 JSON，并限制节点数、坐标范围、属性大小和连接合法性。
+- 禁止在节点脚本、公式、插件或导入文件中执行任意 JavaScript。
+- 外部图片、图标和链接使用允许协议/Origin；Data URL、SVG 和第三方图标库单独评审。
+- Canvas/SVG 视图提供可访问的节点列表、属性面板或导出文本，核心操作支持键盘。
+- SVG/图片/PDF 导出作为不可信文件处理，不把未清理 SVG 重新注入应用 DOM。
+
+## 性能、供应链和验收
+
+- Feature 路由与 Adapter 双层动态加载；编辑器 SDK、语言包、字体和 Worker 不进入首屏包。
+- 设置单个编辑器路由的 JS、内存、初始化时间和大文档交互预算，并在目标设备测量。
+- 评审 SDK 许可证、维护状态、CVE、遥测默认值、插件权限、CSP、Worker 和退出/迁移能力。
+- 使用 P2-02 Feature Flag/Kill Switch 控制新会话；供应商故障提供安全只读或静态预览。
+- 测试快速文档切换、卸载销毁、无权限、dirty、保存失败、导出竞态、恶意文档、迁移
+  缺口/循环、大文档、键盘操作和目标浏览器兼容性。
+
+Knip 只把 `src/optionalEditors` 视为脚手架可选公共入口；项目没有选择供应商前，不新增
+地图、富文本或图形编辑器依赖。

package/template/docs/page-feedback.md

@@ -0,0 +1,83 @@
+# 页面反馈与错误恢复
+
+`src/components/PageFeedback` 提供页面首次加载、成功空态和无可用内容错误态。它只负责
+统一展示和无障碍语义，不持有 TanStack Query 状态、不自动重试，也不决定 Feature 的
+业务动作。页面仍然是查询状态和业务文案的所有者。
+
+## 状态判定
+
+| 查询与内容状态               | 页面行为                                            |
+| ---------------------------- | --------------------------------------------------- |
+| 首次请求执行中且没有可用内容 | `PageLoadingState`                                  |
+| 请求成功且业务集合确实为空   | `PageEmptyState`，可传入新建或清空筛选动作          |
+| 请求失败且没有可用内容       | `PageErrorState`，按 `ApiError.bRetriable` 提供重试 |
+| 后台刷新且已有缓存内容       | 保留内容，只在局部显示刷新进度                      |
+| 后台刷新失败但仍有可用旧内容 | 保留内容，使用非阻塞提示，不替换成整页错误态        |
+| 查询被取消                   | 不向用户显示错误                                    |
+| 权限或其他不可重试错误       | 显示错误说明和业务后续动作，不显示重试              |
+
+加载态只用于首次无内容请求，不能在每次 `isFetching` 时卸载已有页面。空态必须来自一次成功
+响应，不能用空数组掩盖请求失败。
+
+## Feature 组合方式
+
+```tsx
+const objListQuery = useTemplateRecordList({
+  objFeature,
+  objInput: { nPage: 1, nPageSize: 20 },
+  strWorkspaceId,
+})
+
+if (objListQuery.isPending) {
+  return <PageLoadingState />
+}
+
+if (objListQuery.isError) {
+  return (
+    <PageErrorState
+      bIsRetrying={objListQuery.isFetching}
+      fnOnRetry={() => void objListQuery.refetch()}
+      objError={objListQuery.error}
+    />
+  )
+}
+
+if (objListQuery.data.arrRecords.length === 0) {
+  return <PageEmptyState objAction={objCreateAction} />
+}
+
+return <RecordList arrRecords={objListQuery.data.arrRecords} />
+```
+
+`PageErrorState` 仅展示标准 `ApiError` 的安全消息和请求 ID。未知 `Error` 的原始消息可能
+包含实现或隐私信息，因此默认使用通用文案。Feature 可以通过 `strTitle` 和
+`strDescription` 提供经过审核的领域文案，通过 `objAction` 提供返回、联系支持等操作。
+
+## 页面内反馈与全局 Toast
+
+一个失败只应有一个主要反馈入口：
+
+- 会阻断页面首次内容的 Query，由页面内 `PageErrorState` 负责；生成客户端请求配置
+  `bShowError: false`，避免同时弹出全局错误 Toast。
+- 后台刷新失败且页面仍有旧数据时保留内容，可使用全局 Toast 或 Feature 内非阻塞提示。
+- Mutation 默认使用统一 Toast；表单字段错误、Dialog 内错误或批量失败明细由局部 UI
+  负责时，同样设置 `bShowError: false`。
+- 401 由会话生命周期和路由处理；路由渲染错误、运行时配置错误继续使用各自的专用错误页。
+
+```ts
+objGeneratedApi.records.recordsList(objParameters, {
+  bShowError: false,
+  signal: objSignal,
+})
+```
+
+`bRetriable` 只控制是否向用户提供手动重试，不代表自动发起请求。自动重试次数、退避和
+幂等安全仍由 Query/Mutation 及后端协议决定。重试执行中应传入 `bIsRetrying`，组件会禁用
+按钮以阻止重复触发。
+
+## 验收要求
+
+- 页面覆盖首次加载、成功空态、无内容失败、无权限、重试中和成功内容状态。
+- 错误页保留请求 ID，未知错误不直接显示内部消息。
+- 动态状态具有 `status`/`alert`、`aria-live` 和忙碌语义，业务动作可使用键盘完成。
+- 页面内错误与全局 Toast 不重复，已有内容不会因后台刷新闪成整页加载态。