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

package/template/docs/scaffold-guide.md

@@ -0,0 +1,443 @@
+# React 管理后台脚手架指南
+
+这个仓库提供可直接扩展的管理后台壳层，不附带产品业务域。新项目应在独立 Feature 中
+实现业务，并通过路由公开页面入口，不要把产品规则写入 `components`、`router` 或
+`stores` 等共享基础设施。
+
+模板维护仓库保留完整能力源；实际项目先生成 `core` 或 `full` 档位。日常项目开发不应
+直接复制整个维护仓库后再人工判断哪些目录可以删除。
+
+## 开箱验收
+
+1. 执行 `pnpm create react-admin-template@latest <项目目录>` 生成默认 core 项目；
+   维护者也可以在模板仓库执行 `pnpm scaffold:create --target <项目目录>`。
+2. 进入目标项目，复制并填写 `tools/scaffold/init.example.json`，先预览再显式写入配置。
+3. 执行 `pnpm scaffold:check`，确认脚手架基础配置可运行。
+4. 接入真实后端时，在 `.env.local` 配置可访问的 `VITE_API_BASE_URL`。
+5. 执行 `pnpm api` 后生成的客户端通过类型检查。
+6. 执行 `pnpm dev` 后可以登录并进入 `/dashboard`。
+7. 首次交付前执行 `pnpm scaffold:check --strict`，处理全部项目化提醒。
+8. 执行 `pnpm verify` 通过完整质量门禁。
+
+### 生成档位与可选能力
+
+```bash
+pnpm create react-admin-template@latest my-admin
+pnpm create react-admin-template@latest my-admin-full --profile full
+pnpm scaffold:create --target ../my-admin
+pnpm scaffold:create --target ../my-admin-full --profile full
+pnpm scaffold:add --target ../my-admin --capability advancedTable
+```
+
+`core` 保留壳层、账号密码登录与会话刷新、路由权限、OpenAPI、Query、枚举与参数、文件、
+Locale、PageForm、AppDataTable、Dialog 和工程门禁。`full` 额外包含高级认证编排、活动
+状态、Feature Flag、高级表格、审计、报表、实时协作、租户/工作空间和可选编辑器。能力
+添加命令必须从完整模板仓库执行，目标项目最终得到普通本地源码，不存在运行时插件加载
+或内部 Node 包依赖。生成器保留同版本锁文件中的依赖快照，避免首次安装升级工具链；
+`.scaffold-state.json` 应提交到目标项目，用于校验模板版本和已启用能力。
+
+### 初始化命令
+
+初始化清单一次性声明项目包名、应用初始版本、公开运行时配置和 OpenAPI 服务。先复制
+示例并填写真实公开值：
+
+```bash
+cp tools/scaffold/init.example.json scaffold.init.json
+pnpm scaffold:init --config scaffold.init.json
+pnpm scaffold:init --config scaffold.init.json --write
+pnpm scaffold:check --strict
+```
+
+不带 `--write` 时只输出 `UPDATE`、`UNCHANGED` 和将变化的字段路径，不修改文件。写入前会
+完成全部校验，并通过临时文件、备份和失败回滚更新以下三个稳定目标：
+
+| 初始化清单字段  | 写入目标                       | 所有权                                       |
+| --------------- | ------------------------------ | -------------------------------------------- |
+| `package`       | `package.json`                 | 更新名称、描述和声明的版本，保留脚本和依赖   |
+| `runtimeConfig` | `public/runtime-config.json`   | 复用浏览器启动时的同一份 Zod 契约            |
+| `apiServices`   | `src/api/config/services.json` | 供 `swagger-typescript-api` 按服务生成客户端 |
+
+清单是严格且带版本的 JSON 契约：未知字段、重复服务名、非法环境变量名、错误运行时字段都会在
+写入前以 `SCAFFOLD_INIT_CONFIG_INVALID` 拒绝。同一清单重复写入不会产生额外 Diff，团队可以
+提交不含密钥的 `scaffold.init.json` 作为初始化记录。
+
+初始化命令不会替换 Logo/Favicon，不会修改认证 Adapter、路由、业务 Feature、`.env` 或生成
+客户端，也不会访问后端。运行时配置和所有 `VITE_*` 值对浏览器公开，初始化清单中禁止
+保存密码、Token、Client Secret 或其他密钥。
+
+应用版本与模板版本是两条独立版本线。`package.json#version` 属于项目发布，
+`scaffold.template.json#strAppliedVersion` 记录项目已经完整应用并验证的模板版本。当前
+没有第二个模板版本，因此不预置升级引擎；完整人工评审与可回滚流程见
+[`template-versioning.md`](template-versioning.md)。
+
+### 初始化检查命令
+
+`pnpm scaffold:check` 是只读预检，不修改文件、不访问后端、不生成 API 客户端，也不执行
+完整生产构建。它检查：
+
+- 当前 Node 是否满足 `package.json#engines.node`，pnpm 和 `.nvmrc` 是否声明完整；
+- development/production 的 Vite 配置能否真实加载，构建变量是否符合约束；
+- `public/runtime-config.json` 能否通过浏览器启动时使用的同一份 Zod 契约；
+- `src/api/config/services.json` 是否具备 swagger-typescript-api 所需的服务定义；
+- 包名、品牌、存储命名空间、认证参数、demo 模式和 `backend` 服务名是否仍是脚手架占位值。
+
+普通模式中，配置错误返回非零退出码，项目化提醒不阻止本地启动。严格模式会把提醒也视为
+首次交付阻断项：
+
+```bash
+pnpm scaffold:check
+pnpm scaffold:check --strict
+```
+
+常见诊断与处理方式：
+
+| 稳定诊断码                      | 含义                              | 处理位置                             |
+| ------------------------------- | --------------------------------- | ------------------------------------ |
+| `BUILD_CONFIG_INVALID`          | Vite 变量缺失、格式或文件路径错误 | `.env.local`、`.env.<mode>.local`    |
+| `RUNTIME_CONFIG_INVALID`        | 运行时 JSON 不符合 Zod 契约       | `public/runtime-config.json`         |
+| `OPENAPI_SERVICES_INVALID`      | OpenAPI 服务清单无效              | `src/api/config/services.json`       |
+| `PACKAGE_NAME_PLACEHOLDER`      | 包名仍是脚手架默认值              | `package.json`                       |
+| `STORAGE_NAMESPACE_PLACEHOLDER` | 存储命名空间尚未项目化            | `runtime-config.json#app`            |
+| `AUTH_CONFIG_PLACEHOLDER`       | 认证公开参数仍为默认值            | `runtime-config.json#auth`           |
+| `DEMO_MODE_ACTIVE`              | 尚未连接真实认证和业务数据        | Runtime Config 与项目 Adapter 组合点 |
+
+检查命令不会验证后端可达性、OpenAPI 文档正确性、商业许可证有效性或生产密钥注入。这些需要在
+对应环境执行 `pnpm api`、`pnpm verify`、部署健康检查和供应商许可验收。
+
+## 第一次定制
+
+环境相关的公开应用配置位于 `public/runtime-config.json`，由
+`src/config/runtimeConfig.ts` 在浏览器启动时校验：
+
+| 配置                           | 用途                                   |
+| ------------------------------ | -------------------------------------- |
+| `app.strTitle`                 | 浏览器标题、登录页和侧边栏品牌名       |
+| `app.strDescription`           | 页面描述和侧边栏副标题                 |
+| `app.strBrandId`               | 稳定白标标识，不参与租户授权           |
+| `app.strLogoPath`              | `public/` 下的 Logo 路径或公开图片地址 |
+| `app.strDarkLogoPath`          | 深色主题 Logo；可与浅色 Logo 相同      |
+| `app.strFaviconPath`           | 浏览器页签图标                         |
+| `app.objTheme`                 | 受限明暗品牌色与浏览器主题色           |
+| `app.strStorageNamespace`      | 认证、主题和 UI 偏好的浏览器存储前缀   |
+| `app.strMode`                  | 演示或真实后端接入模式                 |
+| `api.strBaseUrl`               | 浏览器运行时 API 基础地址              |
+| `auth`                         | Audience、Client ID、Scope 和认证端点  |
+| `auth.strSessionStorage`       | `memory` 或当前标签页的 `session`      |
+| `observability.bEnabled`       | 是否允许发送脱敏诊断事件               |
+| `observability.strEnvironment` | 当前部署环境名称                       |
+| `locale.strLocale`             | 共享文案、Intl 和后端元数据语言        |
+| `locale.strTimeZone`           | 日期时间统一使用的 IANA 时区           |
+| `navigation`（`appConfig.ts`） | 登录成功与根路由进入的默认页面         |
+
+`app.strStorageNamespace` 变更后，旧命名空间中的浏览器会话不会自动迁移。应在首次发布前
+确定该值。运行时 JSON 和 `VITE_*` 变量都会暴露给浏览器，不能保存任何密钥。
+
+同一构建产物可以按部署注入不同品牌名称、明暗 Logo、Favicon 和经过 WCAG AA 校验的语义
+色，不需要复制源码。任意 CSS、字体和脚本不属于运行时契约；完整字段、资产降级和回滚方式
+见 [`white-label.md`](white-label.md)。
+
+推荐初始化顺序：
+
+1. 使用 `scaffold:init` 统一写入包名、运行时公开配置和 OpenAPI 服务清单。
+2. 替换 `public/logo.svg` 与 `public/favicon.ico`。
+3. 按项目需要补充 `package.json` 的仓库元数据。
+4. 在 `.env.local` 配置本地可访问的 OpenAPI 服务地址。
+5. 根据后端协议调整 `src/api/authClient.ts` 和 `src/api/authSession.ts` 的认证适配。
+6. 创建第一个业务 Feature 并注册路由。
+7. 需要线上监控时，在 `src/config/observabilityAdapter.ts` 接入供应商 Adapter。
+8. 更新部署配置和许可证，然后运行 `pnpm verify`。
+9. 执行 `pnpm scaffold:check --strict`，确认没有遗留脚手架占位配置。
+
+## 模块边界
+
+```text
+src/
+  config/       应用品牌、入口和持久化契约
+  router/       路由组合、守卫和回跳策略
+  api/          OpenAPI、请求生命周期、枚举、参数和元数据编排
+  files/        上传、下载、预览和导入导出任务契约
+  locale/       统一语言、时区、Intl 格式化和共享文案
+  permissions/  响应式操作权限 Hook 与纯权限契约
+  features/     页面级能力，内部拥有自己的 UI、规则、状态和请求
+  components/   不包含产品策略的共享组件
+  context/      全局 React Provider
+  stores/       跨 Feature 且确有持久化需求的客户端状态
+  observability/ 结构化事件、脱敏策略和监控 Adapter 契约
+```
+
+Feature 之间不应互相引用内部文件。跨 Feature 工作流由路由页或更高层组合；只有语义、
+生命周期和维护责任都稳定的能力才能进入共享目录。
+
+边界门禁遵循以下导入契约：
+
+- 每个 `src/features/<featureName>` 都必须存在 `index.ts` 或 `index.tsx`。
+- Feature 外部和其他 Feature 只能导入 `@/features/<featureName>`，不能拼接内部路径。
+- Feature 不得导入 `@/router`、`@/layouts`、`@/Application` 或 `@/main`；共享策略下沉到
+  `api/`、`config/`、`lib/` 等基础层，上层编排则通过参数或组件属性注入。
+- Feature 内部使用相对路径，白盒测试可以直接测试内部文件，但不得因此增加公共导出。
+
+静态导入、动态 `import()` 和再导出都会由 ESLint 检查；新增一级 Feature 缺少公共入口
+会由 `pnpm test:config` 阻断。
+
+## 新增业务页面
+
+1. 先执行 `pnpm scaffold:feature --name <featureName> --model <ModelName> --resource
+<resource>` 预览，再追加 `--write` 生成 Feature 数据边界和契约测试。
+2. 用真实 Swagger DTO、Repository Adapter、权限码和领域规则替换生成的中性记录语义。
+3. 只在 Feature 根 `index.ts(x)` 暴露路由需要的页面，再从
+   `src/router/lazyRouteComponents.ts` 懒加载 `@/features/<featureName>`。
+4. 在 `src/router/config.ts` 注册路由，通过 `staticData` 声明标题、图标和菜单排序。
+5. 需要登录的页面挂在 `_app` 路由下；访客页面挂在 `_guest` 路由下。
+6. 根据真实用户行为更新生成的测试，并补充需要的集成测试。
+
+业务请求必须使用 `src/api/generated` 中的客户端，不能绕过统一认证、刷新和错误处理。
+生成参数、冲突保护、生成客户端接线和双模式示例见
+[`feature-data-template.md`](feature-data-template.md)。模板自身不注册路由，也不会进入默认
+`src/features`、菜单或首屏包；其源码只作为生成器资产保存在 `tools/scaffold/templates`。
+
+## 保留的基础设施
+
+- 认证、会话续期和受保护路由
+- 错误页、响应式布局、主题与菜单搜索
+- 页面首次加载、成功空态、请求错误、请求 ID 与手动重试反馈
+- 后端驱动的全局枚举与参数目录、作用域缓存、运行时校验与统一失效
+- 路由、操作、表格和请求共用的权限判断与授权快照刷新
+- shadcn/ui 以及通用表单、表格、弹窗、日期和 JSON 编辑组件
+- OpenAPI 生成脚本、`ApiError`、请求关联 ID 和统一请求 Hook
+- 用户、认证租户、语言和会话隔离的 Query Key，以及显式工作空间作用域与 Mutation 约定
+- 文件上传、下载、图片/PDF 预览和同步/异步任务 Adapter
+- Locale Provider、统一 Intl 格式化和 Feature 自有语言包入口
+- 可按需加入的租户/工作空间上下文、后端确认切换、缓存隔离和失败恢复
+- 通知未读数、近期任务状态、轮询/SSE/WebSocket Adapter 和断线恢复
+- Mutation 幂等键、防重复激活、结果未知恢复和后端确认控制器
+- AppTable 查询、排序、分页、字段偏好、显式/跨页选择和工具栏回调
+- Feature 组合权限、幂等 Mutation、批量后端接口和 AppDialog
+- PageForm/AppTable dirty 状态与统一路由、刷新、关闭保护
+- 供应商无关可观测性 Adapter、默认拒绝脱敏策略和发布版本上下文
+- 可独立关闭的 Web Vitals 采集、CSP 契约测试和依赖漏洞审计
+- ESLint、Prettier、Stylelint、Knip、Vitest Browser、Playwright 与 CI
+
+### 组件能力清单
+
+`src/components/ui` 只保留当前壳层或内建能力实际使用的全局 shadcn primitives。新项目
+需要其他 primitive 时通过 shadcn CLI 加入，禁止在业务能力中复制第二份。项目自有组件
+按下表管理：
+
+| 能力类型     | 内建组件                                               | 使用约束                              |
+| ------------ | ------------------------------------------------------ | ------------------------------------- |
+| 数据交互     | `AppDataTable`、`AppPageForm`                          | core 默认内建，Feature 从根入口导入   |
+| 高级数据交互 | `AppTable`                                             | `advancedTable` 能力按需加入          |
+| 文件交互     | `FileUpload`、`FilePreview`                            | 生成客户端和外部服务通过 Adapter 注入 |
+| 页面反馈     | `PageLoadingState`、`PageEmptyState`、`PageErrorState` | 页面拥有请求状态，组件只负责展示      |
+| 弹窗反馈     | `AppDialog`、`RouteDialog`、`StatusBadge`              | 不得内置产品文案、权限或业务枚举      |
+| 操作权限     | `Can`、`usePermission`                                 | 权限码由 Feature 声明，后端最终授权   |
+| 日期输入     | `DateRangePicker`、`DateTimePicker`                    | 统一使用全局日期与表单 primitives     |
+| 内容编辑     | `JsonEditor`                                           | `optionalEditors` 能力按需加入        |
+
+`StatusBadge` 仅为少量通用状态提供默认色调。业务状态必须显式传入 `strTone`，避免共享
+组件暗含某个产品的状态语义。新增或移除脚手架能力时，应同步维护本清单和对应公共契约
+测试。
+
+文件能力的生成客户端适配、取消、Blob 内存上限、预览 Origin 和服务端职责见
+[`file-capabilities.md`](file-capabilities.md)。
+
+语言、时区、格式化、共享文案覆盖和 Feature 语言包边界见
+[`locale-and-i18n.md`](locale-and-i18n.md)。
+
+Feature 的 Query Key 层级、失效矩阵、乐观更新回滚和同资源 Mutation 并发策略见
+[`query-data-conventions.md`](query-data-conventions.md)。
+
+租户/工作空间 Adapter、切换顺序、React/非 React 入口和缓存边界见
+[`tenant-workspace-context.md`](tenant-workspace-context.md)。
+
+活动快照、未读数、任务状态、三种传输方式和安全重连接入见
+[`activity-status.md`](activity-status.md)。
+
+幂等 Mutation、生成客户端请求头、按钮状态和超时结果确认见
+[`mutation-idempotency.md`](mutation-idempotency.md)。
+
+AppTable 已统一查询、排序、分页、偏好、显式/跨页选择和工具栏回调。业务 Feature
+直接消费这些回调，并用 generated 批量接口、权限、幂等 Mutation 与 `AppDialog` 组合流程；
+不要再建立一套平行的页面筛选或批量操作状态机。
+
+页面加载、空态、错误恢复以及页面内反馈和全局 Toast 的归属规则见
+[`page-feedback.md`](page-feedback.md)。
+
+共享组件不应包含某个产品的文案、状态枚举或接口类型。新增依赖前应先确认浏览器或现有
+组件不能满足需求，并为依赖建立明确的消费边界。
+
+## 操作与请求权限
+
+认证会话中的 `objUser.arrPermissions` 是前端唯一权限源。路由元数据、菜单、命令搜索、
+`usePermission`、`Can` 和请求守卫都读取这份身份快照；不要为按钮再建立权限 Context 或
+Zustand Store。单个权限码直接传字符串，多权限可传数组并用 `all` 或 `any` 指定匹配方式：
+
+```tsx
+const bCanWrite = usePermission('inventory:item:write')
+
+<Can objRequirement='inventory:item:write'>
+  <Button>编辑</Button>
+</Can>
+
+<Can
+  objRequirement='inventory:item:write'
+  strDeniedBehavior='disable'
+>
+  {({ bIsDisabled }) => <Button disabled={bIsDisabled}>编辑</Button>}
+</Can>
+```
+
+默认使用隐藏策略；需要向用户解释“功能存在但不可用”时才保留禁用态。禁用模式使用
+Render Props，由调用方把 `bIsDisabled` 写到真实交互元素，避免只给外层容器加样式却
+仍可触发操作。`AppTable` 不内置业务权限码，Feature 通过同一个结果设置现有工具栏按钮
+的 `hidden` 或 `disabled`：
+
+```tsx
+const bCanExport = usePermission('inventory:item:export')
+
+const arrButtons = [
+  {
+    key: 'export',
+    label: '导出',
+    hidden: !bCanExport,
+    onClick: fnExport,
+  },
+]
+```
+
+可见性不能替代服务端授权。TanStack Query 和 Mutation 直接调用生成客户端：
+
+```tsx
+const objScope = useAppQueryScope()
+const objKeys = fnCreateAppQueryKeys('inventory', objScope)
+
+useQuery({
+  queryKey: objKeys.fnLists('items'),
+  queryFn: ({ signal: objSignal }) =>
+    objInventoryApi.api.inventoryItemsList({ signal: objSignal }),
+})
+
+useMutation({
+  mutationFn: (objInput) =>
+    objInventoryApi.api.inventoryItemsCreate(objInput),
+})
+```
+
+后端必须对每个请求重新授权，并通过统一 `401/403 ApiError` 返回拒绝结果。前端不在
+数据层重复维护一套权限判定，避免权限刷新不同步时产生与后端相反的结果。
+刷新接口可以在 `objUser` 中返回最新权限、角色和租户；授权上下文变化后脚手架会提升
+会话版本、清理旧 Query/枚举数据、重新校验当前路由并自动刷新可见操作。
+
+## 全局参数与元数据初始化
+
+全局参数用于后端集中维护、跨 Feature 读取的公开业务配置，例如导出行数上限、支持
+文案或某项通用交互是否开放。它不等同于 `runtime-config.json`：运行时配置决定应用在
+哪个环境以及如何连接服务；全局参数是登录后按租户、会话代次和语言加载的服务端数据。
+参数接口禁止返回密码、Token、私钥或其他客户端不应持有的秘密，也不能替代后端权限和
+Feature Flag 的服务端决策。
+
+推荐接口为 `/api/v1/meta/parameters`，响应 `data` 使用以下结构；项目也可以通过 Adapter
+映射不同的后端 DTO：
+
+```json
+{
+  "version": "2026.08.26",
+  "locale": "zh-CN",
+  "parameters": {
+    "application.allowExport": {
+      "type": "boolean",
+      "value": true,
+      "description": "是否展示通用导出入口"
+    },
+    "application.maxExportRows": {
+      "type": "number",
+      "value": 5000
+    }
+  }
+}
+```
+
+支持 `boolean`、有限 `number`、`string` 和 JSON 数组/对象/`null`。目录在进入 Query
+缓存前校验类型、语言、版本和 JSON 有效性，并深度冻结复合值；调用方读取的预期类型与
+后端声明不一致时抛出带稳定错误码的 `GlobalParameterError`，不会静默转换字符串和数字。
+
+使用 `swagger-typescript-api` 生成客户端后，在应用组合点创建数据源：
+
+```tsx
+const objGlobalParameterSource = fnCreateGlobalParameterSource(
+  async ({ objScope, objSignal, strLocale }) => {
+    const objResponse = await objMetadataApi.api.apiV1MetaParametersGet(
+      {
+        locale: strLocale,
+        tenantId: objScope.strTenantId,
+      },
+      { signal: objSignal }
+    )
+    return objResponse.data
+  }
+)
+
+objRoot.render(
+  <Application
+    objMetadata={{
+      objGlobalParameters: { objSource: objGlobalParameterSource },
+    }}
+  />
+)
+```
+
+React Feature 使用准确类型 Hook；完整目录和通用值可分别读取：
+
+```tsx
+const objAllowExport = useBooleanGlobalParameter(
+  'application.allowExport'
+)
+const objMaxRows = useNumberGlobalParameter(
+  'application.maxExportRows'
+)
+const objCatalog = useGlobalParameterCatalog()
+```
+
+React 外部使用 `fnEnsureGlobalParameters` 预加载、
+`fnGetCachedGlobalParameters` 同步读取 Query 缓存，再配合
+`fnGetBooleanGlobalParameter`、`fnGetNumberGlobalParameter`、
+`fnGetStringGlobalParameter`、`fnGetJsonGlobalParameter`、
+`fnGetGlobalParameterKeys` 和 `fnGetGlobalParameterValue`。参数维护成功后调用
+`fnInvalidateGlobalParameters`，不能把服务端值复制进 Zustand 或在 Feature 中永久缓存。
+
+`MetadataProvider` 是应用层编排边界：未登录时默认不请求；登录后枚举与参数并行加载；
+租户、会话代次或语言变化会切换隔离后的 Query Key。任何一个资源失败都不会替换或隐藏
+应用子树，相关 Feature 分别通过 `useEnumCatalog()` 或
+`useGlobalParameterCatalog()` 的错误状态与 `fnRefetch()` 展示降级和重试。当前两个目录没有
+互相依赖，不再维护重复的聚合状态，也禁止为了“统一初始化”人为制造串行请求瀑布。
+
+## 无障碍与核心旅程测试
+
+浏览器测试运行在 Playwright Chromium 中，不使用 DOM 模拟器声明真实焦点行为。
+`tests/setup/accessibility.ts` 提供 axe 断言，应用集成测试至少覆盖：
+
+- 浅色和深色登录壳层的语义、标签与颜色对比度。
+- 登录后的应用壳层，无严重或关键 axe 违规。
+- 纯键盘登录、受保护首页到达、用户菜单退出和会话回到登录页。
+- 表单校验后焦点进入首个错误字段；Dialog 等复合控件继续由所属组件测试焦点进入、
+  Escape 和恢复行为。
+
+axe 只扫描当前 React 测试容器，避免把 Vitest Browser 自己的界面计入结果。发现违规时
+应修复语义、交互或全局主题令牌，不得通过关闭规则维持绿灯。自动扫描不能证明完整
+无障碍，新 Feature 仍需用真实键盘验证操作顺序、可见焦点、动态反馈和适用的焦点恢复。
+
+## 交付约束
+
+- 支持版本以 `package.json#engines`、`.nvmrc` 和 `packageManager` 为准。
+- `pnpm api` 的生成结果不提交，但 `src/api/generated` 是生成器拥有的工作目录，不得作为
+  冗余内容手工清理；生成模板、服务清单与原子替换流程都属于脚手架契约。
+- `pnpm verify` 是提交和合并前的统一门禁。
+- 模板升级只通过独立 Git 分支、Changelog、人工冲突处理和 `pnpm verify` 落地；规则见
+  [`template-versioning.md`](template-versioning.md)。
+- `pnpm build` 会基于 Vite Manifest 校验入口、登录、中性首页和全局 CSS 的 gzip 预算；
+  阈值、Owner 与调整规则见 [`bundle-budgets.md`](bundle-budgets.md)。
+- CI 在门禁通过后执行 `pnpm release:prepare`；后续镜像和部署只能消费带文件摘要与 Commit
+  身份的 `.artifacts/release`，不得再次构建前端。
+- `runtime-config.json` 是环境配置，不进入不可变发布目录；部署按镜像 Digest 拉取后注入。
+- `dist/`、`.artifacts/`、本地缓存、环境私有配置和凭据不得提交。
+- 对外分发前必须确认仓库许可证和 Handsontable 商业授权。

package/template/docs/template-changelog.md

@@ -0,0 +1,30 @@
+# 模板变更记录
+
+本文件记录脚手架公共契约对派生项目的影响，不记录普通业务 Feature 的内部提交。应用自身
+版本继续使用 `package.json#version`；项目已应用的模板版本记录在
+`scaffold.template.json`，两者独立演进。
+
+## 0.1.0 - 2026-08-28
+
+首个受治理的模板基线，包含：
+
+- React 19、TypeScript、Vite、路由、认证和运行时配置壳层；
+- 源码内置的 PageForm、Table、反馈、文件、枚举和全局参数等企业通用能力；
+- Swagger/OpenAPI 生成器、Feature 生成器、初始化检查、架构边界、浏览器测试、构建体积
+  预算和不可变发布产物门禁。
+
+这是初始版本，不需要从旧模板执行迁移。
+
+## 维护规则
+
+每次模板发布必须同步完成：
+
+1. 在本文件中先写派生项目能观察到的变化，再写迁移步骤、验证方式和废弃周期；不能只列
+   内部 Commit。
+2. 将 `scaffold.template.json#strAppliedVersion` 更新为新版本，使新创建项目记录准确基线。
+3. 在至少两个派生项目验证迁移步骤，并运行 `pnpm verify`。
+4. 模板升级必须作为独立 Git 提交或合并请求落地。回滚恢复整个升级提交，不允许只降低
+   `strAppliedVersion` 掩盖已经进入源码和配置的变化。
+
+SemVer 按派生项目影响解释：删除或改变公共入口、类型、初始化契约、CSS/交互行为以及更
+严格且会拒绝旧配置的校验都可能是破坏性变更；仅修改模板内部实现不能自动视为兼容。

package/template/docs/template-versioning.md

@@ -0,0 +1,26 @@
+# 模板版本与升级策略
+
+脚手架和派生项目有两条独立版本线。项目应用版本来自 `package.json#version`；已经应用的
+模板版本来自 `scaffold.template.json#strAppliedVersion`。两者不能互相替代。
+
+当前模板只有 `0.1.0` 一个已发布基线，没有真实的跨版本迁移消费者，因此不维护模板目录、
+连续路径算法或自动覆盖工具。提前建设升级引擎只会增加规则和维护成本，不能证明真实项目的
+认证、路由、主题与业务定制能够自动合并。
+
+## 当前升级流程
+
+1. 模板维护者在 [`template-changelog.md`](template-changelog.md) 记录派生项目可观察的变化。
+2. 项目团队为模板同步创建独立 Git 分支，保持业务改动与模板改动分离。
+3. 按 Changelog 通过合并、Cherry-pick 或明确补丁应用变化，人工处理项目定制冲突。
+4. 运行 `pnpm components:diff`、相关回归测试和 `pnpm verify`。
+5. 源码、配置和 `scaffold.template.json` 在同一提交或合并请求中更新。
+6. 出现回归时恢复完整升级提交，不能只降低模板版本字段。
+
+## 何时再建设迁移工具
+
+只有出现第二个稳定模板版本，并且至少两个派生项目需要执行相同、可机械化、可幂等的迁移
+时，才为该次具体变化建设窄范围 Codemod 或升级检查。工具必须有真实输入样本、失败诊断、
+重复执行测试和完整 Git 回滚方案，不能演变成通用源码合并器。
+
+模板 SemVer 按消费者影响解释：公共入口、类型、初始化契约、CSS/交互行为或更严格的输入
+拒绝都可能构成破坏性变化。应用自己的 Changelog、发布节奏和版本号不受模板版本牵制。

package/template/docs/tenant-workspace-context.md

@@ -0,0 +1,147 @@
+# 租户与工作空间上下文
+
+这套能力统一管理“当前请求属于哪个租户和工作空间”，不提供租户列表、成员管理或切换
+页面。租户/工作空间列表仍是服务端数据，应由具体项目的 Feature 通过生成客户端和
+TanStack Query 加载；前端上下文只保存后端已经确认过的稳定 ID。
+
+它不进入默认 `core`。先从完整模板仓库按需复制，公共入口统一从
+`@/tenantWorkspace` 导入：
+
+```bash
+pnpm scaffold:add --target ../my-admin --capability tenantWorkspace
+```
+
+能力不会偷偷修改应用根。项目需要在组合点显式挂载 Provider，并决定切换前取消哪些请求、
+切换后重新校验哪些路由。
+
+## 状态所有权
+
+| 状态                   | 唯一所有者                     | 持久化与隔离                                          |
+| ---------------------- | ------------------------------ | ----------------------------------------------------- |
+| 当前租户 ID            | 认证会话 `objUser.strTenantId` | 跟随会话；变化会提升会话版本并清空 QueryClient        |
+| 当前工作空间 ID        | `tenantWorkspace` 上下文       | 只保存经后端确认的 ID，并绑定当前 `userId + tenantId` |
+| 租户/工作空间列表      | 所属 Feature 的 TanStack Query | 不复制进全局 Store                                    |
+| 切换中、失败和重试目标 | `tenantWorkspace` 切换事务     | 仅保留在内存，刷新后不恢复未完成事务                  |
+| Token、角色和权限      | 认证会话                       | 跨租户切换必须由后端返回完整新会话                    |
+
+工作空间选择使用带应用命名空间的 Local Storage Key。持久化值不被当作授权凭证：当前认证
+用户或租户不匹配时不会生效，并由 Provider 清理；每个后端请求仍必须重新校验成员关系和权限。
+
+## 切换顺序
+
+`fnSwitchTenantWorkspace()` 和 `useTenantWorkspace().fnSwitch()` 使用相同事务：
+
+```text
+标准化稳定目标 ID
+        ↓
+取消更早的切换请求
+        ↓
+项目 Adapter 调用后端并校验成员关系
+        ↓
+校验返回目标；跨租户必须带新认证会话
+        ↓
+取消旧上下文仍在运行的 Query
+        ↓
+提交新会话 → 提交工作空间 → 重新校验当前路由
+```
+
+后端确认前旧上下文始终生效。Adapter 失败、结果不一致、缺少跨租户会话或提交前取消时，
+旧租户、工作空间和缓存身份都不改变。用户连续切换时采用“最后一次请求生效”；旧 Adapter
+收到 `AbortSignal`，即使它忽略取消并稍后返回，也不能覆盖较新的选择。
+
+## 接入 Swagger 生成客户端
+
+项目在组合点实现 `ITenantWorkspaceAdapter`，不要在基础设施中写死接口路径或生成 DTO。
+下面的接口名只是接线形状，实际字段由项目后端契约决定：
+
+```ts
+import { Application } from '@/Application'
+import { objQueryClient, objRouter } from '@/router/router'
+import {
+  TenantWorkspaceProvider,
+  type ITenantWorkspaceAdapter,
+} from '@/tenantWorkspace'
+
+const objTenantWorkspaceAdapter: ITenantWorkspaceAdapter = {
+  fnSwitch: async ({ objSignal, objTarget }) => {
+    const objResponse = await objGeneratedApi.api.switchContext(
+      {
+        tenantId: objTarget.strTenantId,
+        workspaceId: objTarget.strWorkspaceId,
+      },
+      { signal: objSignal }
+    )
+
+    return {
+      strTenantId: objResponse.data.tenantId,
+      strWorkspaceId: objResponse.data.workspaceId,
+      // 跨租户时在项目 Adapter 中把后端 DTO 映射为完整 IAuthSession。
+      objSession: fnMapContextSession(objResponse.data.session),
+    }
+  },
+}
+
+objRoot.render(
+  <TenantWorkspaceProvider
+    fnAfterCommit={() => void objRouter.invalidate()}
+    fnBeforeCommit={() => objQueryClient.cancelQueries()}
+    objAdapter={objTenantWorkspaceAdapter}
+  >
+    <Application />
+  </TenantWorkspaceProvider>
+)
+```
+
+同租户工作空间切换在 Token 和权限不变时可以不返回 `objSession`。如果权限或 Token 随
+工作空间变化，也应返回完整会话，让现有认证生命周期统一提升会话版本、清缓存和刷新
+路由。禁止只在客户端修改租户 ID，或从旧会话拼接一个“看起来属于新租户”的用户对象。
+
+## React 与非 React 使用
+
+普通组件读取当前上下文并发起切换：
+
+```tsx
+const {
+  fnCancel,
+  fnClearError,
+  fnRetry,
+  fnSwitch,
+  objCurrent,
+  objTransition,
+} = useTenantWorkspace()
+
+await fnSwitch({
+  strTenantId: objTenant.strId,
+  strWorkspaceId: objWorkspace.strId,
+})
+```
+
+`objTransition` 是 `idle | switching | error` 可判别联合。失败状态保留 `objTarget` 和带稳定
+`strCode` 的 `TenantWorkspaceError`，页面可以展示旧上下文、提供重试或清除错误。组件卸载
+或用户主动停止时调用 `fnCancel()`。
+
+路由 Loader、命令处理器等 React 外代码使用 `fnGetTenantWorkspaceCurrent()` 或
+`fnGetTenantWorkspaceSnapshot()`。需要在 React 外切换时，显式把 Adapter 和生命周期依赖
+传给 `fnSwitchTenantWorkspace()`，避免隐藏的全局 API 注册表。
+
+## Query、枚举和参数隔离
+
+- 默认 `useAppQueryScope()` 只从认证会话读取用户和租户，不依赖该可选能力。
+- 启用后，所属 Feature 从 `useTenantWorkspace()` 读取 `objCurrent.strWorkspaceId`，并显式传给
+  `useAppQueryScope({ strWorkspaceId })`；跨空间管理页也按同样方式传入自己的目标空间。
+- 工作空间变化会产生新的 Query Key；切换提交前取消旧作用域的活动请求，旧缓存不能被
+  新 Key 读取。
+- 租户变化必须提交新认证会话，现有认证生命周期会清空全部服务端查询缓存。
+- 枚举与全局参数默认按认证租户隔离。确实存在工作空间级元数据时，由项目组合层把当前
+  `strWorkspaceId` 显式传入 `objMetadata` 的对应 `objScope`；失败不替换旧作用域事实。
+
+工作空间 ID 只负责缓存身份，不能替代请求参数或后端授权。若接口需要工作空间字段，
+Repository 仍应把当前 ID 明确传给生成客户端。
+
+## 不支持范围
+
+- 不内置租户选择器、工作空间树、成员管理、套餐或计费页面。
+- 不保存租户/工作空间名称、列表、权限或其他服务端事实。
+- 不用 Local Storage 选择替代后端成员关系校验。
+- 不为不同项目假定“租户”和“组织/项目”的层级关系。
+- 不允许切换失败后自动回退到 Demo 数据或另一个猜测的工作空间。