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

package/template/README.md

@@ -0,0 +1,372 @@
+# Enterprise React Admin Scaffold
+
+面向团队内部项目的 React 19、TypeScript 与 Vite 管理后台脚手架，精简自
+[satnaing/shadcn-admin](https://github.com/satnaing/shadcn-admin)。本仓库是完整能力源；
+新项目默认生成精简的 `core` 档位，不包含系统管理、产品业务页面和低频可选能力。
+
+## 内置能力
+
+- `/sign-in`：管理员登录入口
+- `/dashboard`：可进入各项实操页面的脚手架演示首页
+- `/showcase/*`：表格、PageForm、枚举参数、上传预览和页面反馈实操页
+- `/errors/401`、`403`、`404`、`500`、`503`：通用错误页
+- `demo` / `connected` 双运行模式，可先演示再接入真实后端
+- TanStack Router 路由守卫、权限过滤、菜单元数据和命令搜索
+- `usePermission`、`Can`、表格与 Query/Mutation 共用的操作权限闭环
+- TanStack Query 作用域 Key、Mutation 一致性、OpenAPI 客户端与统一请求生命周期
+- Mutation 幂等键、防重复激活、超时恢复与后端结果确认
+- `AppTable` 内建查询、排序、分页、偏好、跨页选择和工具栏操作入口
+- 批量提交、确认与结果反馈由 Feature 组合权限、幂等 Mutation 和 `AppDialog`
+- 工具层中性 Feature 生成器，预览并生成 DTO 映射、Repository、双 Adapter 和契约测试
+- 后端驱动的全局枚举、类型安全全局参数与非阻塞元数据初始化
+- 源码内置的 `AppDataTable` 承载常规 CRUD；高级电子表格源码通过能力清单按需加入
+- PageForm 与可选高级 Table 都以项目源码交付，不依赖内部 Git 包
+- `pnpm components:check` 持续校验内建组件来源、回归证据和第三方许可证边界
+- 页面首次加载、成功空态、请求错误、请求 ID 和手动重试的统一反馈组件
+- 文件上传、下载、图片/PDF 预览与同步/异步任务的可替换 Adapter 契约
+- 统一 Locale、IANA 时区、Intl 格式化及 Feature 自有语言包入口
+- shadcn/ui、Tailwind CSS、浅色/深色主题和响应式侧边栏
+- 可插拔可观测性、Web Vitals、默认拒绝日志采集及版本/Commit/环境上下文
+- CI 单次构建、静态文件摘要、Commit 身份和镜像 Digest 驱动的不可变产物晋级
+- 候选容器使用真实 Chromium 校验 Runtime Config、React 启动和登录路由
+- 默认入口、登录和中性首页按静态 Chunk 图执行 gzip 体积预算
+- 可预览、显式写入、失败回滚且可重复执行的脚手架初始化命令
+- 应用与模板独立版本化，模板变化通过 Changelog、人工评审和完整 Git 回滚管理
+- 同一构建产物按 Runtime Config 切换名称、明暗 Logo、Favicon 和可访问品牌色
+- Vitest Browser、Playwright、ESLint、Prettier、Stylelint、Knip 与 CI
+
+品牌、API、认证公开参数和浏览器存储命名空间由 `public/runtime-config.json` 在启动时
+加载；Vite 构建参数保留在 `.env`。新项目的初始化与 Feature 接入流程见
+[`docs/scaffold-guide.md`](docs/scaffold-guide.md)。
+企业能力边界、模块分级和接入契约见
+[`docs/enterprise-scaffold.md`](docs/enterprise-scaffold.md)。
+完整能力状态、验收标准和逐项建设顺序见
+[`docs/scaffold-capability-roadmap.md`](docs/scaffold-capability-roadmap.md)。
+多品牌运行时字段、资产安全和部署回滚规则见
+[`docs/white-label.md`](docs/white-label.md)。
+
+## 开始使用
+
+通过 npm 创建默认的 `core` 项目：
+
+```bash
+pnpm create react-admin-template@latest my-admin
+cd my-admin
+pnpm dev
+```
+
+需要完整能力源时添加 `--profile full`。npm 包只负责创建项目；React、PageForm、Table、
+枚举和 API 生成工具最终都以源码形式进入新项目，不形成内部运行时包依赖。
+
+查看当前仓库的完整演示：
+
+```bash
+pnpm install
+pnpm dev
+```
+
+打开终端输出的地址（默认 `http://localhost:8848`），使用演示账号
+`13800000000`、密码 `admin123` 登录。登录后的 `/dashboard` 是演示导航页，可以进入表格
+CRUD 与高级网格、PageForm 校验与联动、全局枚举与参数、文件上传预览、页面反馈与弹窗等
+独立实操页面。开发端口被占用时 Vite 会明确报错；关闭旧的开发进程，或在 `.env.local`
+中设置新的 `VITE_PORT` 后重新启动，避免误开旧服务页面。
+
+从本仓库创建一个新项目：
+
+```bash
+pnpm install
+pnpm scaffold:create --target ../my-admin
+cd ../my-admin
+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
+pnpm dev
+```
+
+`scaffold:create` 默认生成 `core` 项目；确实需要完整能力源时使用
+`--profile full`。从模板仓库为已有 core 项目加入能力：
+
+```bash
+pnpm scaffold:add --target ../my-admin --capability advancedTable
+```
+
+可选能力为 `activityStatus`、`advancedAuthentication`、`advancedTable`、`auditLogs`、
+`featureFlags`、`optionalEditors`、`realtimeCollaboration`、`reporting` 和
+`tenantWorkspace`。命令复制源码、测试与文档，并同步依赖和组件治理清单；不会安装第三方
+业务 SDK。生成出的
+`.scaffold-state.json` 记录档位、模板版本和已启用能力，应随项目源码提交，供后续能力添加
+时校验来源一致性。
+
+Node 版本由 `.nvmrc` 声明，包管理器版本由 `package.json#packageManager` 声明。
+`scaffold:init` 默认只预览，只有 `--write` 才更新包名、公开运行时配置和 OpenAPI 服务清单；
+它不会改动 Logo、认证 Adapter、业务 Feature 或环境密钥。
+`scaffold:check` 会验证工具链、Vite 构建配置、运行时 JSON 和 OpenAPI 服务清单；原始模板
+出现项目名、品牌和 demo 模式提醒属于预期，首次交付前执行 `pnpm scaffold:check --strict`
+必须全部处理。
+应用版本使用 `package.json#version`，已应用模板版本使用 `scaffold.template.json`。
+当前只有首个模板基线，不维护没有真实迁移消费者的升级引擎；后续版本通过 Changelog、
+独立 Git 提交和人工合并升级。详见
+[`docs/template-versioning.md`](docs/template-versioning.md)。
+脚手架默认以 `demo` 模式启动，不依赖后端。项目配置真实 OpenAPI 服务后再执行
+`pnpm api` 生成客户端；生成行为应放在拥有可访问契约地址的独立 CI 任务中。
+
+仅模板维护仓库包含创建器，发布说明位于
+`packages/create-react-admin-template/README.md`。
+在该包目录执行 `pnpm publish` 会自动生成模板并运行发布前验证；生成项目不包含该目录，
+根应用不直接发布。
+
+## 应用配置
+
+浏览器先以 `no-store` 加载 `public/runtime-config.json`，通过 Zod 校验并冻结后才加载认证、
+路由和应用模块。加载或校验失败时会展示独立诊断页，不会带着错误配置继续发送请求。
+
+| 运行时字段                     | 用途                                          |
+| ------------------------------ | --------------------------------------------- |
+| `app.strTitle`                 | 浏览器标题、登录页和侧边栏品牌名              |
+| `app.strDescription`           | 页面描述和侧边栏副标题                        |
+| `app.strLogoPath`              | `public/` 下的 Logo 路径或公开图片地址        |
+| `app.strStorageNamespace`      | 认证、主题和 UI 偏好的浏览器存储命名空间      |
+| `app.strMode`                  | `demo` 使用本地演示适配器；`connected` 接后端 |
+| `api.strBaseUrl`               | API 基础地址；空字符串表示当前站点            |
+| `auth.strAudience`             | 登录请求使用的认证 Audience                   |
+| `auth.strClientId`             | 登录和刷新请求使用的公开 OAuth Client ID      |
+| `auth.strScope`                | 登录请求申请的 OAuth Scope                    |
+| `auth.strSessionStorage`       | `memory` 不落盘；`session` 仅保留在当前标签页 |
+| `auth.strSignInPath`           | 登录端点                                      |
+| `auth.strRefreshPath`          | Token 刷新端点                                |
+| `auth.strSignOutPath`          | 注销端点                                      |
+| `observability.bEnabled`       | 是否向项目 Adapter 发送脱敏诊断事件           |
+| `observability.strEnvironment` | local、test、staging、production 等部署环境   |
+| `locale.strLocale`             | 共享文案、格式化与后端元数据使用的语言        |
+| `locale.strTimeZone`           | 日期时间统一使用的 IANA 时区                  |
+
+下面的变量属于开发或构建环境，不应放入运行时 JSON：
+
+| 构建变量                        | 用途                                      |
+| ------------------------------- | ----------------------------------------- |
+| `VITE_PORT`                     | 本地 Vite 开发服务端口                    |
+| `VITE_DEV_HTTPS_CERT_PATH`      | 可选的本地 HTTPS 证书路径                 |
+| `VITE_DEV_HTTPS_KEY_PATH`       | 可选的本地 HTTPS 私钥路径                 |
+| `VITE_PUBLIC_PATH`              | 应用部署基础路径                          |
+| `VITE_API_PROXY`                | 本地同源 API 代理前缀                     |
+| `VITE_API_BASE_URL`             | OpenAPI 与开发代理使用的后端地址          |
+| `VITE_DEV_API_INSECURE_TLS`     | 是否仅在开发代理中跳过上游 TLS 校验       |
+| `VITE_HANDSONTABLE_LICENSE_KEY` | Handsontable 许可证；生产必须使用商业 key |
+
+本机差异写入 `.env.local` 或 `.env.<mode>.local`。所有 `VITE_*` 值都会进入浏览器
+产物；运行时 JSON 同样对浏览器公开，两者都不得存放密码、Token、Client Secret 或其他
+密钥。部署时可以替换 `runtime-config.json` 而不重新构建 `dist` 或镜像。
+
+Vite 配置不合法时，`dev` 和 `build` 会以 `BUILD_CONFIG_INVALID` 列出具体变量与修复动作，
+不会只输出底层解析堆栈。浏览器运行时配置失败仍由独立诊断页展示稳定错误码和版本信息。
+
+## API 与认证
+
+后端服务模板位于 `src/api/config/services.json`，执行 `pnpm api` 后生成客户端到
+`src/api/generated/<服务名>`。其中 `backend` 只是中性占位名；初始化项目时应替换
+OpenAPI 地址。生成结果不提交，也不应手工修改。
+
+`src/api/generated` 是 `swagger-typescript-api` 生成器拥有的工作目录。它虽然被 Git
+忽略，但不是冗余目录，仓库清理不得手工删除其中的客户端；需要刷新时只能执行
+`pnpm api`。生成脚本先在临时目录完成全部服务，再原子替换正式目录，因此下载或生成
+失败时必须保留上一次成功产物。
+
+业务源码必须通过生成客户端访问后端，ESLint 会阻止直接使用 `fetch` 或 Axios 请求方法。
+`src/api/hooks` 负责 Authorization、并发 Token 刷新、401 会话清理和统一错误处理；
+`src/api/authClient.ts` 只封装登录、刷新和退出三个认证端点，避免基础壳层加载完整业务
+客户端。新项目更换认证协议时，应从该适配器和 `src/api/authSession.ts` 开始。
+
+实例化生成客户端时，应将 `objAppConfig.api.strBaseUrl` 传给客户端的 `baseURL`，确保
+业务请求和认证请求使用同一份运行时 API 地址。
+
+### 标准错误与请求关联
+
+所有生成客户端和认证客户端都会在请求前写入 `X-Request-ID`。调用方已经提供合法 ID
+时保持不变，否则使用浏览器生成的新 ID；响应优先采用服务端的 `X-Request-ID`，其次
+读取 `X-Correlation-ID` 或响应体中的 `requestId/traceId`，最后回退到客户端 ID。
+
+除主动取消外，请求失败统一抛出 `ApiError`：
+
+| 字段           | 含义                                                         |
+| -------------- | ------------------------------------------------------------ |
+| `message`      | 已限制长度并过滤控制字符的用户文案                           |
+| `strCode`      | 后端业务码、`HTTP_<status>` 或稳定客户端错误码               |
+| `strKind`      | `http`、`network`、`timeout`、`client` 或 `invalid_response` |
+| `nStatus`      | 可选 HTTP 状态码                                             |
+| `strRequestId` | 服务端或客户端请求关联 ID                                    |
+| `objDetails`   | 后端明确提供的 `details/errors`，用于字段错误等业务处理      |
+| `bRetriable`   | 是否适合再次尝试；只是提示，不会自动重放请求                 |
+
+`ApiError` 不保存 Axios config、Authorization 或完整原始响应。全局 Toast 只展示安全文案和
+请求 ID，不展开 `objDetails`；取消请求继续保留 Axios `CanceledError`，业务代码可以正常
+区分用户取消和真实失败。
+
+后端应原样接收或重新生成 `X-Request-ID`，将最终 ID 写回响应头和服务端日志。跨域部署还
+必须返回：
+
+```http
+Access-Control-Expose-Headers: X-Request-ID, X-Correlation-ID
+```
+
+请求 ID 只能用于关联日志，不能放入用户信息、Token、租户密钥或其他敏感内容。
+
+## 可观测性、脱敏与版本
+
+`src/observability` 提供供应商无关的 Adapter，统一覆盖浏览器未捕获异常、未处理 Promise、
+路由渲染错误、应用启动和 API 错误。每个事件会自动附加 `package.json` 版本、Git Commit、
+构建时间及 `runtime-config.json` 中的部署环境；侧边栏和错误页也会显示可检索的版本信息。
+
+生产环境默认没有第三方 SDK。项目在 `src/config/observabilityAdapter.ts` 接入 Sentry、
+OpenTelemetry 或企业日志平台，并在运行时配置中开启 `observability.bEnabled`。Adapter
+只接收 `IObservabilityEvent`，不得要求基础层传递原始 Axios 请求、响应或用户对象：
+
+```ts
+import type { IObservabilityAdapter } from '@/observability'
+
+export const objProjectObservabilityAdapter: IObservabilityAdapter = {
+  fnCaptureEvent(objEvent) {
+    objMonitoringSdk.captureEvent(objEvent)
+  },
+}
+```
+
+日志上下文采用默认拒绝策略：只允许请求 ID、HTTP 状态、稳定错误码、错误类别、重试
+标记、路由 ID 和生命周期阶段等声明过的标量字段。Token、Authorization、Cookie、
+密码、邮箱、手机号、请求体、响应体、嵌套对象和未知 Key 均不会进入 Adapter；错误消息
+与调用栈还会执行二次脱敏和长度限制。事件自动包含版本和环境，但不发送 URL、DOM 节点
+或用户数据。`bEnabled=false` 时完全不产生诊断事件，供应商
+Adapter 抛错或拒绝 Promise 也不会影响应用运行。
+
+浏览器响应头、CSP 变更和依赖审计规则见
+[`docs/browser-security.md`](docs/browser-security.md)。
+
+版本和 Commit 在构建时写入静态产物，部署环境在运行时注入，因此同一不可变产物晋级
+到不同环境时不需要重新构建。上述字段都是公开诊断信息，不得把分支凭据、流水线 Token
+或其他密钥作为版本字段。
+
+生产运行时配置应使用 `memory`，Bearer Token 不写入 Web Storage，刷新页面后需要重新
+建立会话。`session` 只适合可信的内部演示环境。若后端支持 BFF/HttpOnly Cookie，应替换认证
+适配器并由服务端管理刷新会话；前端环境变量无法把 JavaScript 可见 Token 变成 HttpOnly。
+
+脚手架不预置用户、角色、组织等业务 Repository。初始化项目时，应在自己的 Feature
+中定义领域契约，并使用生成的 OpenAPI 客户端实现 connected Adapter；业务页面不能
+直接依赖演示数据，也不能在连接失败时回退到 demo 数据。
+
+### 全局枚举目录
+
+所有由后端管理、需要跨页面展示的枚举统一通过 `src/api/enums` 消费。后端接口返回完整
+枚举目录，TanStack Query 按语言负责缓存、并发去重、取消和失效；不要再把目录复制到
+Zustand，也不要在 Feature 内维护重复的 `value/label` 数组。
+
+后端目录契约为 `/api/v1/meta/enums`，响应 `data` 包含 `version`、`locale` 和以稳定
+Enum Key 为索引的 `enums`。项目生成客户端后，在应用组合点完成一次结构化适配：
+
+```tsx
+const objEnumApi = fnConfigureApiClient(new Api<void>())
+const objEnumCatalogSource = fnCreateEnumCatalogSource(
+  async ({ objSignal, strLocale }) => {
+    const objResponse = await objEnumApi.api.apiV1MetaEnumsGet(
+      { locale: strLocale },
+      { signal: objSignal }
+    )
+    return objResponse.data
+  }
+)
+
+objRoot.render(
+  <Application
+    objMetadata={{ objEnumCatalog: { objSource: objEnumCatalogSource } }}
+  />
+)
+```
+
+`Application` 默认只在认证完成后加载枚举，自动把当前租户和会话权限版本纳入缓存
+作用域。公共枚举接口可通过 `objMetadata.objEnumCatalog.bIsEnabled` 显式启用；存在工作
+空间或产品模块时，通过 `objMetadata.objEnumCatalog.objScope` 增加 `strWorkspaceId` 或
+`strNamespace`。作用域只能包含稳定
+标识，禁止放入 Access Token 等凭据。
+
+Feature 使用 `useEnum('domain.resource.status')` 获取单个枚举的标准选项和查询状态；
+表格、表单、筛选器和状态展示都从同一结果派生。需要枚举管理页或批量转换时，使用
+`useEnumCatalog()` 获取 `arrEntries`、`arrKeys`、`fnGetOptions`、`fnGetValues`、
+`fnGetLabel`、`fnGetLabels` 和 `fnGetValue`。枚举值原样保留后端的 `string`、`number`
+或 `boolean` 类型；停用选项继续展示历史文案，但通过 `disabled` 阻止表单和表格产生
+新的选择。
+
+普通文本和状态展示可直接使用 `EnumText`、`EnumBadge`。`EnumBadge` 只接受设计系统
+允许的语义色调，不会把后端颜色字段当作 CSS 执行：
+
+```tsx
+<EnumText strEnumKey='activity.status' objValue={objRow.status} />
+<EnumBadge strEnumKey='activity.status' objValue={objRow.status} />
+```
+
+React 外部可用 `fnGetCachedEnumCatalog(objQueryClient)` 同步读取缓存，再配合
+`fnGetEnumKeys`、`fnGetEnumOptions`、`fnGetEnumValues` 等纯函数；路由 Loader 仍使用
+`fnEnsureEnumCatalog` 确保目录已加载。后端枚举变更后调用
+`fnInvalidateEnumCatalog(objQueryClient)`，不能在客户端覆盖后端值或显示文本。
+
+同一个枚举 Key 内的 Value 和本地化 Label 都必须唯一；目录不满足契约时会抛出带
+`strCode` 的 `EnumCatalogError`，避免 Label 反查静默选择错误值。
+
+### 全局参数与元数据编排
+
+跨 Feature 的后端公开参数统一由 `src/api/parameters` 管理，支持 `boolean`、有限
+`number`、`string` 和 JSON 值。目录在进入 TanStack Query 缓存前执行类型、语言和版本
+校验，并按租户、权限版本、工作空间、命名空间和语言隔离。禁止把全局参数复制到 Zustand，
+也禁止通过参数接口向浏览器下发秘密。
+
+React 中可使用 `useBooleanGlobalParameter`、`useNumberGlobalParameter`、
+`useStringGlobalParameter`、`useJsonGlobalParameter`、`useGlobalParameter` 和
+`useGlobalParameterCatalog`。React 外部使用 `fnEnsureGlobalParameters`、
+`fnGetCachedGlobalParameters` 及各类型读取函数；维护完成后通过
+`fnInvalidateGlobalParameters` 统一失效。
+
+`MetadataProvider` 在认证完成后并行装配枚举和参数。登录、租户、权限版本或语言变化会
+自然切换作用域；单个资源失败不会阻塞 Router 和无关页面。需要状态和重试时分别使用
+`useEnumCatalog()` 与 `useGlobalParameterCatalog()`，避免维护重复的聚合状态。生成客户端
+适配和完整后端契约见
+[`docs/scaffold-guide.md`](docs/scaffold-guide.md#全局参数与元数据初始化)。
+
+## 目录
+
+```text
+src/
+  config/       应用级配置
+  router/       路由组合、守卫和回跳策略
+  api/          OpenAPI、请求生命周期和认证适配
+  features/     认证、错误页以及新项目自己的业务 Feature
+  components/   通用组件和 shadcn/ui primitives
+  context/      全局 React Provider
+  layouts/      应用布局
+  stores/       跨 Feature 的持久化客户端状态
+```
+
+## 验证
+
+```bash
+pnpm verify
+```
+
+该命令依次执行代码规范、组件源码治理、死代码检查、真实 Chromium 浏览器测试（包含 axe
+与核心键盘旅程）、类型检查和生产构建。提交信息遵循 Conventional Commits；生成的
+`dist/`、本地缓存、凭据和私有环境配置不得提交。
+
+内建组件升级前，使用只读差异命令核对正确来源、前向 revision 和纳入范围：
+
+```bash
+pnpm components:diff -- \
+  --component AppTable \
+  --source-root /absolute/path/to/table-component
+```
+
+命令不会同步文件或更新 revision。完整流程见
+[`docs/component-source-governance.md`](docs/component-source-governance.md)。
+
+## License
+
+当前仓库尚未声明对外分发许可证。发布或开源前需确认仓库许可证，并单独确认
+仅在启用高级 `AppTable`（Handsontable）时确认其商业使用授权；生产构建不会接受
+评估许可证。组件来源、同步和外部分发门禁见
+[`docs/component-source-governance.md`](docs/component-source-governance.md)。

package/template/build/advancedTable.ts

@@ -0,0 +1,103 @@
+import type { Plugin, Rolldown } from 'vite'
+
+interface IAppTableBuildGuardOptions {
+  /** Vite 合并后的 Handsontable 许可证，不会写入诊断信息。 */
+  strLicenseKey?: string
+}
+
+const strAdvancedTableVendorChunk = 'advanced-table-vendor'
+const strHandsontableEvaluationLicense = 'non-commercial-and-evaluation'
+
+function fnNormalizeModuleId(strModuleId: string) {
+  return strModuleId.replaceAll('\\', '/')
+}
+
+function fnIsAppTableSourceModule(strModuleId: string) {
+  return fnNormalizeModuleId(strModuleId).includes('/src/components/AppTable/')
+}
+
+function fnIsHandsontableModule(strModuleId: string) {
+  const strNormalizedId = fnNormalizeModuleId(strModuleId)
+  return (
+    strNormalizedId.includes('/node_modules/handsontable/') ||
+    strNormalizedId.includes('/node_modules/.pnpm/handsontable@')
+  )
+}
+
+function fnChunkContainsAdvancedTable(objChunk: Rolldown.OutputChunk) {
+  return Object.keys(objChunk.modules).some(
+    (strModuleId) =>
+      fnIsAppTableSourceModule(strModuleId) ||
+      fnIsHandsontableModule(strModuleId)
+  )
+}
+
+function fnCollectInitialChunks(objBundle: Rolldown.OutputBundle) {
+  const objChunks = new Map(
+    Object.values(objBundle)
+      .filter(
+        (objOutput): objOutput is Rolldown.OutputChunk =>
+          objOutput.type === 'chunk'
+      )
+      .map((objChunk) => [objChunk.fileName, objChunk])
+  )
+  const arrPendingFiles = [...objChunks.values()]
+    .filter((objChunk) => objChunk.isEntry)
+    .map((objChunk) => objChunk.fileName)
+  const objInitialFiles = new Set<string>()
+
+  while (arrPendingFiles.length > 0) {
+    const strFileName = arrPendingFiles.pop()
+    if (!strFileName || objInitialFiles.has(strFileName)) continue
+    objInitialFiles.add(strFileName)
+    const objChunk = objChunks.get(strFileName)
+    if (objChunk) arrPendingFiles.push(...objChunk.imports)
+  }
+
+  return [...objInitialFiles]
+    .map((strFileName) => objChunks.get(strFileName))
+    .filter((objChunk): objChunk is Rolldown.OutputChunk => Boolean(objChunk))
+}
+
+/** 创建高级表格生产许可证与首屏静态依赖守卫。 */
+export function fnCreateAppTableBuildGuard({
+  strLicenseKey,
+}: IAppTableBuildGuardOptions): Plugin {
+  return {
+    name: 'enterprise:app-table-build-guard',
+    apply: 'build',
+    generateBundle(_objOptions, objBundle) {
+      const arrChunks = Object.values(objBundle).filter(
+        (objOutput): objOutput is Rolldown.OutputChunk =>
+          objOutput.type === 'chunk'
+      )
+      if (!arrChunks.some(fnChunkContainsAdvancedTable)) return
+
+      if (
+        !strLicenseKey ||
+        strLicenseKey === strHandsontableEvaluationLicense
+      ) {
+        this.error(
+          '[APP_TABLE_LICENSE_REQUIRED] 生产产物包含 AppTable，' +
+            '必须配置 VITE_HANDSONTABLE_LICENSE_KEY 商业许可证。'
+        )
+      }
+
+      if (
+        fnCollectInitialChunks(objBundle).some(fnChunkContainsAdvancedTable)
+      ) {
+        this.error(
+          '[APP_TABLE_EAGER_LOAD] AppTable 或 Handsontable 进入了首屏静态依赖。' +
+            '请仅在按需加载的 Feature 路由中导入 AppTable。'
+        )
+      }
+    },
+  }
+}
+
+/** 将 Handsontable 固定到高级表格异步 Vendor Chunk。 */
+export function fnResolveAdvancedTableManualChunk(strModuleId: string) {
+  if (fnIsHandsontableModule(strModuleId)) {
+    return strAdvancedTableVendorChunk
+  }
+}

package/template/build/environment.ts

@@ -0,0 +1,150 @@
+import path from 'path'
+import { existsSync } from 'node:fs'
+
+interface IBuildConfigIssue {
+  /** 对应的公开环境变量名。 */
+  strKey: string
+  /** 不回显配置值的失败原因。 */
+  strProblem: string
+  /** 开发者可以直接执行的修复动作。 */
+  strFix: string
+}
+
+interface IResolveBuildEnvironmentOptions {
+  /** Vite 按当前 Mode 合并后的公开环境变量。 */
+  objEnv: Record<string, string>
+  /** 当前执行的是开发服务还是生产构建。 */
+  strCommand: 'build' | 'serve'
+  /** 用于解析证书等相对文件路径的项目根目录。 */
+  strProjectRoot: string
+}
+
+function fnIsSafeAbsoluteHttpUrl(strValue: string) {
+  try {
+    const objUrl = new URL(strValue)
+    return (
+      ['http:', 'https:'].includes(objUrl.protocol) &&
+      !objUrl.username &&
+      !objUrl.password
+    )
+  } catch {
+    return false
+  }
+}
+
+function fnIsValidPublicPath(strValue: string) {
+  if (strValue.startsWith('/')) return strValue.endsWith('/')
+  return fnIsSafeAbsoluteHttpUrl(strValue) && strValue.endsWith('/')
+}
+
+function fnThrowBuildConfigIssues(arrIssues: IBuildConfigIssue[]) {
+  if (arrIssues.length === 0) return
+
+  const strDetails = arrIssues
+    .map(
+      (objIssue) =>
+        `- ${objIssue.strKey}: ${objIssue.strProblem}\n  修复：${objIssue.strFix}`
+    )
+    .join('\n')
+  const objError = new Error(
+    `[BUILD_CONFIG_INVALID] Vite 配置校验失败。\n${strDetails}\n` +
+      '修正后执行 pnpm scaffold:check，再重新启动或构建。'
+  )
+  objError.name = 'BuildConfigError'
+  throw objError
+}
+
+/** 校验并规范化 Vite 构建与开发服务器使用的环境变量。 */
+export function fnResolveBuildEnvironment({
+  objEnv,
+  strCommand,
+  strProjectRoot,
+}: IResolveBuildEnvironmentOptions) {
+  const arrIssues: IBuildConfigIssue[] = []
+  const strPublicPath = objEnv.VITE_PUBLIC_PATH?.trim() ?? ''
+  const nPort = Number(objEnv.VITE_PORT)
+  const strApiBaseUrl = objEnv.VITE_API_BASE_URL?.trim()
+  const strApiProxy = objEnv.VITE_API_PROXY?.trim()
+  const strHttpsCertPath = objEnv.VITE_DEV_HTTPS_CERT_PATH?.trim()
+  const strHttpsKeyPath = objEnv.VITE_DEV_HTTPS_KEY_PATH?.trim()
+  const strInsecureTls = objEnv.VITE_DEV_API_INSECURE_TLS?.trim().toLowerCase()
+  const strHandsontableLicenseKey = objEnv.VITE_HANDSONTABLE_LICENSE_KEY?.trim()
+
+  if (!strPublicPath || !fnIsValidPublicPath(strPublicPath)) {
+    arrIssues.push({
+      strKey: 'VITE_PUBLIC_PATH',
+      strProblem: '必须是以 / 开头、以 / 结尾的路径或安全的 HTTP(S) URL。',
+      strFix: '在 .env 或对应 Mode 文件中配置，例如 VITE_PUBLIC_PATH=/。',
+    })
+  }
+
+  if (strCommand === 'serve') {
+    if (!Number.isInteger(nPort) || nPort < 1 || nPort > 65_535) {
+      arrIssues.push({
+        strKey: 'VITE_PORT',
+        strProblem: '开发服务端口必须是 1 到 65535 之间的整数。',
+        strFix: '在 .env.local 中设置未被占用的端口，例如 VITE_PORT=8848。',
+      })
+    }
+    if (strApiBaseUrl && !fnIsSafeAbsoluteHttpUrl(strApiBaseUrl)) {
+      arrIssues.push({
+        strKey: 'VITE_API_BASE_URL',
+        strProblem: '必须是不包含用户名或密码的绝对 HTTP(S) URL。',
+        strFix: '在 .env.local 中配置可访问的开发后端地址。',
+      })
+    }
+    if (
+      strApiProxy &&
+      !/^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*$/.test(strApiProxy)
+    ) {
+      arrIssues.push({
+        strKey: 'VITE_API_PROXY',
+        strProblem: '必须是以 / 开头且不包含查询参数或片段的代理前缀。',
+        strFix: '使用类似 /api 的路径，或留空以禁用开发代理。',
+      })
+    }
+    if (strInsecureTls && !['false', 'true'].includes(strInsecureTls)) {
+      arrIssues.push({
+        strKey: 'VITE_DEV_API_INSECURE_TLS',
+        strProblem: '只接受 true 或 false。',
+        strFix: '仅本地自签名后端需要设为 true，其他情况使用 false。',
+      })
+    }
+    if (Boolean(strHttpsCertPath) !== Boolean(strHttpsKeyPath)) {
+      arrIssues.push({
+        strKey: 'VITE_DEV_HTTPS_CERT_PATH / VITE_DEV_HTTPS_KEY_PATH',
+        strProblem: '本地 HTTPS 证书和私钥必须同时配置。',
+        strFix: '同时填写两个文件路径，或同时留空关闭本地 HTTPS。',
+      })
+    } else {
+      for (const [strKey, strFilePath] of [
+        ['VITE_DEV_HTTPS_CERT_PATH', strHttpsCertPath],
+        ['VITE_DEV_HTTPS_KEY_PATH', strHttpsKeyPath],
+      ] as const) {
+        if (
+          strFilePath &&
+          !existsSync(path.resolve(strProjectRoot, strFilePath))
+        ) {
+          arrIssues.push({
+            strKey,
+            strProblem: '配置的文件不存在或当前进程不可访问。',
+            strFix: '改为相对项目根目录的有效文件路径，或清空两项配置。',
+          })
+        }
+      }
+    }
+  }
+
+  fnThrowBuildConfigIssues(arrIssues)
+
+  return {
+    bApiInsecureTls: strInsecureTls === 'true',
+    nPort,
+    strApiBaseUrl,
+    strApiProxy,
+    strHandsontableLicenseKey,
+    strHttpsCertPath,
+    strHttpsKeyPath,
+    strPublicPath,
+  }
+}

package/template/commitlint.config.js

@@ -0,0 +1,32 @@
+/** @type {import('@commitlint/types').UserConfig} */
+export default {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'body-leading-blank': [2, 'always'],
+    'footer-leading-blank': [1, 'always'],
+    'header-max-length': [2, 'always', 108],
+    'subject-empty': [2, 'never'],
+    'type-empty': [2, 'never'],
+    'type-enum': [
+      2,
+      'always',
+      [
+        'feat',
+        'fix',
+        'perf',
+        'style',
+        'docs',
+        'test',
+        'refactor',
+        'build',
+        'ci',
+        'chore',
+        'revert',
+        'wip',
+        'workflow',
+        'types',
+        'release',
+      ],
+    ],
+  },
+}

package/template/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles/index.css",
+    "baseColor": "slate",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}