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

package/template/docs/enterprise-scaffold.md

@@ -0,0 +1,208 @@
+# 企业 React 管理脚手架方案
+
+## 目标
+
+这个仓库是企业内部管理系统的启动底座，不是某个产品的克隆，也不是页面示例集合。
+初始化后应同时满足三个条件：没有产品业务语义、无后端也能完整演示、接入后端时不重写
+页面和路由。
+
+默认面向桌面端内部管理后台，以登录用户中的租户 ID 隔离缓存；工作空间切换上下文按需
+加入，不默认提供计费、套餐、开放注册等 SaaS 能力，也不承诺移动端查看、审批或操作体验。
+现有窄窗口布局用于桌面窗口缩放，不代表建立移动端产品能力。
+
+## 能力分层
+
+### P0：开箱即可开发
+
+| 领域     | 内置能力                                         | 交付形态                |
+| -------- | ------------------------------------------------ | ----------------------- |
+| 应用壳层 | 品牌、主题、侧边栏、面包屑、命令搜索、错误边界   | 可直接使用              |
+| 身份会话 | 登录、退出、刷新、回跳、会话过期                 | demo/connected 双适配器 |
+| 访问控制 | 路由、菜单、按钮和数据请求的统一权限判断         | 权限码契约              |
+| 业务扩展 | Feature、Repository 与 API Adapter 接入约定      | 文档与目录约束          |
+| 数据交互 | PageForm、Table、Dialog、反馈、空态和加载态      | 项目自有组件边界        |
+| API      | OpenAPI 生成、统一错误、请求标识、取消和缓存     | 基础设施                |
+| 初始化   | 项目标识、Runtime Config、OpenAPI 清单与占位诊断 | 预览式写入与只读检查    |
+| 发布     | 单次构建、文件摘要、镜像 Digest 与环境配置注入   | 不可变产物晋级          |
+| 诊断安全 | 错误追踪、Web Vitals、脱敏、CSP 与依赖审计       | 可关闭 Adapter 与门禁   |
+| 工程质量 | 类型、Lint、死代码、浏览器测试、构建和 CI        | `pnpm verify`           |
+
+默认应用只提供“演示登录 → 权限路由 → 中性首页”的壳层闭环。用户、角色、组织等
+系统管理同样属于具体项目业务，初始化后按 Feature 接入，不在脚手架中预置页面或数据。
+
+### P1：企业项目常见增强
+
+- 租户/工作空间上下文：按需加入稳定 ID、后端确认切换、缓存隔离和失败恢复，不内置管理页面。
+- 通知与任务状态：按需加入活动摘要、轮询/SSE/WebSocket Adapter 和断线恢复，不内置待办页。
+- 幂等写事务：统一幂等键、按钮状态、超时恢复和后端结果确认，不用前端防抖冒充幂等。
+- 批量操作：Table 负责选择和入口，Feature 负责权限、确认、提交及业务结果反馈。
+- 页面筛选：Table 负责查询、排序、分页与偏好；可分享 URL 由具体路由按需定义。
+- 任务中心：待办、已办、抄送、批量处理和未读提醒。
+- 审批接入：审批详情、意见、附件和流转记录；不内置可视化流程设计器。
+- 字典与参数：通用枚举、远程选项缓存和环境级参数。
+- 文件能力：上传、下载、预览、失败重试和权限校验。
+- 国际化：语言包、日期、时区和数字格式策略。
+- 业务审计：高风险操作留痕、后端审计 ID 和用户可见操作记录。
+
+### P2：按项目选择
+
+- 租户级品牌、计费套餐和跨租户运营能力。
+- SSO/OIDC、MFA、设备管理和高风险操作二次确认。
+- Feature Flag、灰度发布、离线能力和微前端承载。
+- 复杂报表、打印模板、地图、富文本和实时协作。
+
+这些能力不应默认进入主包；通过明确的 Feature 或 Adapter 接入。
+
+## 运行模式契约
+
+`runtime-config.json` 中 `app.strMode=demo` 时，仅认证使用内存数据。默认演示账号为
+`13800000000`，密码为 `admin123`。刷新页面可恢复初始演示数据，不产生网络写入。
+
+`app.strMode=connected` 时，认证 Adapter 连接真实服务。生产部署通过环境专属的运行时
+配置文件使用该模式。项目新增的业务 Feature 应自行定义 Repository 契约，并用生成的 OpenAPI
+客户端实现；真实数据不得在页面组件中分支，也不得在连接失败时回退到 demo 数据。
+
+可复制的中性 DTO、Repository、Demo/Connected Adapter、Query 和 Mutation 实现见
+[`feature-data-template.md`](feature-data-template.md)。模板不注册路由，真实 Feature
+复制后拥有自己的契约，不能把模板变成跨业务共用的万能 CRUD 层。
+
+```text
+Route / Feature
+      │
+      ▼
+Domain repository contract
+      │
+      ├── demo adapter（内存数据）
+      └── connected adapter（OpenAPI client）
+```
+
+## 权限契约
+
+权限使用稳定的 `domain:resource:action` 字符串，例如 `inventory:item:read` 和
+`inventory:item:write`；具体权限码由接入项目定义，脚手架不预置业务权限。
+
+路由元数据声明进入页面所需的权限；侧边栏和命令搜索从同一份路由元数据生成并自动
+过滤。页面中的写操作还必须单独检查写权限，不能因为页面可见就默认允许修改。
+后端仍是最终授权边界，前端权限只负责体验与提前阻断。
+
+操作权限通过 `usePermission` 和 `Can` 直接读取认证身份；表格使用同一判断结果设置
+工具栏与单元格动作的 `hidden/disabled`。Query/Mutation 使用请求权限包装器在调用生成
+客户端前阻断无权操作。刷新接口返回新身份时，权限、角色或租户变化会统一清理服务端
+缓存并重新校验当前路由，不建立独立权限 Store。
+
+全局枚举和全局参数都由 TanStack Query 持有服务端真相，并由 `MetadataProvider` 在认证
+完成后按租户、会话代次和语言并行加载。参数值在进入缓存前根据后端声明的
+`boolean/number/string/json` 类型校验，提供 React 与非 React 读取入口。任一目录失败只
+影响使用该资源的 Feature，可单独重试，不得用全屏初始化状态阻塞无关页面。
+
+## 模块边界
+
+```text
+app shell → router → feature → repository contract → api adapter
+                       │
+                       └── owned UI components
+```
+
+- `features/` 只包含按领域组织的页面、领域模型和用例。
+- `components/` 是脚手架自有 UI；常规 CRUD 使用源码内置的 `AppDataTable`，PageForm
+  与高级 Table 通过项目入口导出并按需加载。
+- `api/` 只处理协议、序列化和请求生命周期，不承载页面状态。
+- `api/activity/` 用 Query 持有活动摘要并隔离传输生命周期，不保存完整通知/任务列表。
+- `api/idempotency/` 只创建和校验幂等键；事务状态、结果确认与恢复能力由后端拥有。
+- `files/` 只处理文件交互生命周期与 Adapter 契约，不包含接口地址、供应商或模板。
+- `locale/` 统一语言、时区、Intl 和共享文案；业务语言包仍归所属 Feature。
+- 可选 `tenantWorkspace/` 只编排当前稳定 ID 和切换事务；列表与成员关系仍归后端和 Feature。
+- `stores/` 只保存会话、主题等跨 Feature 状态，服务端数据交给 TanStack Query。
+- Feature 之间不得直接导入内部文件；共享行为提升到公共组件或基础设施。
+
+上述边界由 ESLint 和配置测试执行：每个一级 Feature 必须提供 `index.ts(x)`；路由、应用层
+和其他 Feature 只能从 `@/features/<featureName>` 公共入口导入，不能访问内部文件；Feature
+不能反向依赖 `router/`、`layouts/`、`Application` 或 `main`。Feature 可直接使用框架路由
+Hook，但共享跳转策略应位于 `lib/` 或由上层组合注入。白盒测试允许直接导入内部单元，
+不为测试扩大生产公共 API。
+
+上传、下载、图片/PDF 预览以及同步/异步导入导出任务已形成独立文件能力层。Feature
+通过生成客户端注入请求；大文件、Office 预览和对象存储通过可替换 Adapter 接入，具体
+接法见 [`file-capabilities.md`](file-capabilities.md)。
+
+应用语言同时驱动共享文案、格式化和后端元数据语言，部署环境使用 IANA 时区固定业务
+日期边界；Feature 语言包不注册进全局目录。详细契约和迁移状态见
+[`locale-and-i18n.md`](locale-and-i18n.md)。
+
+默认 core 的当前租户以认证会话为唯一来源，不建立工作空间全局状态。需要切换时加入
+`tenantWorkspace` 能力：工作空间选择绑定用户与租户、切换先由后端确认，跨租户时还必须
+返回新会话。缓存隔离、失败重试和 generated API Adapter 见
+[`tenant-workspace-context.md`](tenant-workspace-context.md)。
+
+有重复副作用风险的 Mutation 使用统一幂等键和结果确认控制器；生成客户端接线、按钮
+状态、超时恢复及后端强制契约见
+[`mutation-idempotency.md`](mutation-idempotency.md)。
+
+`AppTable` 统一提供显式/跨页选择和工具栏回调。批量业务请求不得在共享组件中推断，
+Feature 应使用后端批量接口，并组合权限、幂等 Mutation 与 `AppDialog` 完成具体流程。
+
+## PageForm 与 Table 内建策略
+
+PageForm 与高级 Table 都由模板维护仓库持有源码，不再依赖内部 Git Node 包。生成的 `core`
+项目默认只包含 PageForm、AppDataTable；高级 Table 通过 `advancedTable` 能力复制到目标项目。
+组件边界如下：
+
+1. 所有页面只依赖 `AppPageForm`、`AppDataTable` 或 `AppTable`，形成稳定的项目边界。
+2. `AppPageForm` 以单个应用组件目录组织，不保留 `core/`、`react/` 或发布包目录。
+3. `AppTable` 保留 `engine/`、`config/`、`styles/` 三个基础边界，React 能力直接按
+   `table/`、`search/`、`selection/`、`toolbar/` 等表格领域组织，不再套 package 或
+   adapter 目录；Feature 只能通过组件根入口使用，不能直接导入实现目录。
+
+不直接把完整多框架仓库复制进 `src/`：Vue Adapter、发布脚本、包管理配置和无关示例
+不属于 React 脚手架。当前 Table 源码基线为提交
+`d11c1a1a9837108da59eec41b482f83f5a8fac73`（package `0.4.0`）；迁移前后必须运行
+原组件测试与应用集成测试，避免悄悄丢失编辑、查询、导出、偏好和授权能力。
+
+标准系统页面不得因为基础列表加载 Handsontable、Excel 导出或公式计算依赖。高级
+`AppTable` 只由确实需要编辑、导出、偏好等能力的 Feature 引入；生产环境还必须配置
+商业许可证，评估许可证会被显式拒绝。
+
+## 页面准入标准
+
+新增到脚手架的页面必须满足：
+
+- 默认路由只承载项目真实需要的页面；演示页面放在项目自有示例或文档中，不进入壳层。
+- demo 与 connected 共用页面和领域契约。
+- 声明读取与写入权限，使用统一页面反馈契约覆盖加载、空、错误、无权限、重试中和成功状态。
+- 页面内错误与全局 Toast 不重复；错误恢复保留请求 ID，已有内容不因后台刷新被整页替换。
+- 键盘可操作，表单错误可定位，并在桌面端常用窗口尺寸和缩放比例下保持可用。
+- 有覆盖用户可见行为的浏览器测试，并通过 `pnpm verify`。
+
+状态判定、`ApiError` 重试边界和生成客户端 `bShowError` 接线见
+[`page-feedback.md`](page-feedback.md)。
+
+应用壳层在真实 Chromium 中执行浅色、深色 axe 冒烟，并以键盘完成登录、进入受保护
+首页和退出旅程。全局 `primary`、`secondary`、`destructive` 与
+`muted-foreground` 语义色必须满足其文本用途的 WCAG AA 对比度；高级表格作用域主题与
+应用主题使用相同的可访问色值。axe 不替代复合控件的键盘和焦点行为测试。
+
+## 建设顺序
+
+具体状态、验收标准和逐项实施顺序统一维护在
+[`scaffold-capability-roadmap.md`](scaffold-capability-roadmap.md)，本文件不再维护第二份
+进度清单。
+
+模板和派生项目独立版本化：应用版本进入发布产物，已应用模板版本进入项目状态文件；升级
+前通过只读目录检查证明连续路径，升级和回滚都以完整 Git 提交为单位。维护契约见
+[`template-versioning.md`](template-versioning.md)。
+
+多品牌采用部署级 Runtime Config：同一不可变构建按站点注入名称、明暗 Logo、Favicon 和
+受限语义色，设计系统继续拥有背景、文字、状态与焦点体系。禁止复制应用源码或通过配置注入
+任意 CSS，契约见 [`white-label.md`](white-label.md)。
+
+每一步都保持主分支可运行，不用未完成的空菜单冒充能力。
+
+新项目安装依赖后先运行 `pnpm scaffold:check`；首次交付前使用 `--strict` 阻断默认包名、
+品牌、存储命名空间、认证参数、demo 模式和占位 OpenAPI 服务名。命令复用 Vite 配置加载和浏览器
+Runtime Config Schema，不维护第二份配置真相。
+
+CI 中只有 `verify` 阶段构建前端，`package` 和 `deploy` 必须校验静态文件摘要、Commit 以及
+Registry 镜像 Digest。环境专属 `runtime-config.json` 不进入镜像摘要，在容器启动前单独
+注入。生产构建还会按入口和关键路由静态依赖图执行 gzip 体积预算，内部 Vite Manifest
+不会进入发布站点。完整预算策略见 [`bundle-budgets.md`](bundle-budgets.md)，晋级、回滚和
+本地验证流程见 [`../deploy/README.md`](../deploy/README.md)。

package/template/docs/feature-data-template.md

@@ -0,0 +1,227 @@
+# 中性 Feature 数据模板
+
+`tools/scaffold/templates/feature` 是 Feature 生成器拥有的源码模板，不属于应用运行时
+`src/features`。它用中性的“记录”演示一个企业 Feature 如何连接 Swagger 生成客户端，
+同时保持领域模型、缓存和页面状态不依赖传输 DTO。模板本身不是万能 CRUD 框架，也不是
+所有 Feature 运行时共同依赖的共享业务模块。
+
+## 目录和所有权
+
+```text
+tools/scaffold/templates/feature/
+  types.ts       DTO、领域模型、Feature 实例和 Hook 契约
+  model.ts       不可信 DTO 的运行时校验、映射与输入规范化
+  repository.ts  Demo/Connected Adapter 选择和数据访问实现
+  queries.ts     Feature 自有的列表、详情 Query 与更新 Mutation
+  index.ts       唯一跨 Feature 公共入口
+```
+
+`index.ts` 是唯一面向 Feature 外部的入口。Feature 内部文件使用相对路径；路由、其他
+Feature 和应用组合层不得直接导入 `model.ts`、`repository.ts`、`queries.ts` 或 `types.ts`。
+该约束由 ESLint 和 `test:config` 自动检查。
+
+依赖方向固定为：
+
+```text
+Feature UI / Route
+       │
+       ▼
+Feature Query hooks ──► 不透明 Feature 运行实例
+       │
+       ▼
+内部 Repository contract ──► Query、权限与错误基础设施
+       │
+       ├── Demo Adapter（Feature 自有内存数据）
+       └── Connected Adapter（swagger-typescript-api 生成客户端）
+                    │
+                    ▼
+              DTO → domain mapping
+```
+
+页面只接收由组合点创建的 `ITemplateRecordFeature`，不读取 Repository 和权限码，不判断
+`demo/connected`，不解析 DTO，也不直接调用生成客户端。服务端数据只存在于 TanStack
+Query；Repository 和 Hook 都不会把它复制到 Zustand。
+
+## 初始化真实 Feature
+
+先用生成器完成确定性改名。下面示例生成 `customerManagement` Feature，领域模型为
+`CustomerRecord`，Query Resource Key 和权限前缀为 `customer:record`：
+
+```bash
+pnpm scaffold:feature --name customerManagement --model CustomerRecord --resource customer:record
+pnpm scaffold:feature --name customerManagement --model CustomerRecord --resource customer:record --write
+```
+
+第一次命令只预览将创建的文件；追加 `--write` 后才会同时生成：
+
+```text
+src/features/customerManagement/
+  index.ts
+  model.ts
+  queries.ts
+  repository.ts
+  types.ts
+tests/unit/features/customerManagement/
+  feature.test.ts
+  publicContract.test.ts
+  queries.test.tsx
+```
+
+参数契约保持刻意收敛：
+
+| 参数         | 约束                               | 所有权                                         |
+| ------------ | ---------------------------------- | ---------------------------------------------- |
+| `--name`     | 1 到 60 位 `lowerCamelCase`        | Feature 目录、公共导入路径与 Query Feature Key |
+| `--model`    | 1 到 60 位 `PascalCase`            | 领域模型、Repository、Hook 和错误码标识        |
+| `--resource` | 小写资源名，可使用 `-` 或 `:` 分段 | Query Resource Key 与读写权限前缀              |
+
+源码目录或测试目录只要存在同名或大小写等价目录，生成器都会以
+`FEATURE_CREATE_CONFLICT` 停止，绝不合并或覆盖文件。写入发生异常时只清理由本次命令创建的
+未完成目录。
+
+生成后继续完成真实接入：
+
+1. 用 `pnpm api` 生成的 DTO 类型替换模板 DTO；不要修改 `src/api/generated`。
+2. 在 `model.ts` 保留运行时校验和 DTO 到领域对象的显式映射。
+3. 在 `repository.ts` 用生成客户端实现 Connected Source，并准备同契约 Demo 数据。
+4. 在 Feature 组合点根据后端授权模型声明真实读写权限码。
+5. 从 Feature 根 `index.ts` 只导出页面或其他 Feature 真正需要的契约。
+6. 根据真实行为更新随模块生成的测试，再显式注册路由。
+
+生成器不会创建产品页面，不会修改 Router、菜单或 `knip.config.ts`，不会调用后端或执行
+`pnpm api`。路由是否存在、页面挂在哪个 Layout、菜单和权限元数据是什么，必须由项目
+根据真实业务显式决定。
+
+生成完成后，真实 Feature 拥有自己的模型、Repository 和查询策略，不依赖工具目录中的
+模板源码。模板作为 `scaffold:feature` 的确定性输入长期保留在工具层，不进入应用生产包；
+删除它会使后续 Feature 生成失败，因此不再把它当作可随意删除的运行时示例。
+
+## 接入 Swagger 生成客户端
+
+脚手架通过 `swagger-typescript-api` 按 `src/api/config/services.json` 生成客户端。生成
+方法已经自动返回响应数据，并通过 `fnConfigureApiClient()` 获得认证刷新、请求 ID、取消和
+标准 `ApiError`。真实方法名和 DTO 名以当前 OpenAPI 契约为准，下面的 `recordsList` 等名称
+只是接线位置示意：
+
+```ts
+import { fnConfigureApiClient } from '@/api'
+import { objAppConfig } from '@/config/appConfig'
+import { Api } from '@/api/generated/backend/Api'
+import type { IConnectedCustomerRecordSource } from '@/features/customerManagement'
+
+const objGeneratedApi = fnConfigureApiClient(
+  new Api<void>({ baseURL: objAppConfig.api.strBaseUrl })
+)
+
+const objConnectedSource: IConnectedCustomerRecordSource = {
+  fnGet: (strRecordId, objSignal) =>
+    objGeneratedApi.records.recordsDetail(strRecordId, {
+      bShowError: false,
+      signal: objSignal,
+    }),
+  fnList: (objInput, objSignal) =>
+    objGeneratedApi.records.recordsList(
+      {
+        keyword: objInput.strKeyword,
+        page: objInput.nPage,
+        pageSize: objInput.nPageSize,
+      },
+      { bShowError: false, signal: objSignal }
+    ),
+  fnUpdate: (objInput) =>
+    objGeneratedApi.records.recordsUpdate(objInput.strRecordId, {
+      enabled: objInput.objChanges.bIsEnabled,
+      expectedRevision: objInput.nExpectedRevision,
+      name: objInput.objChanges.strName,
+    }),
+}
+```
+
+如果生成 DTO 字段可选、接口使用响应信封或命名不同，只在 Connected Source 和 `model.ts`
+处理。不要为了匹配页面而修改 Eta 模板或生成文件，也不要把 Axios Response 传到 Feature
+UI。模板保留 `id/name/enabled/revision/items/total` 外部字段名，是为了明确展示 DTO 与
+`strId/strName/bIsEnabled/nRevision/arrRecords/nTotal` 领域模型之间的边界。
+
+## Demo/Connected 组合
+
+应用组合点从同一个运行时配置创建 Feature 运行实例。它一次性隐藏 Repository、权限和
+模式选择；Connected 缺少数据源时会立即报错，不会在网络故障或配置错误时静默回退到
+Demo 数据：
+
+```ts
+const objRecordFeature = fnCreateCustomerRecordFeature({
+  strMode: objAppConfig.runtime.strMode,
+  strReadPermission: 'domain:record:read',
+  strWritePermission: 'domain:record:write',
+  objConnectedSource,
+  arrDemoRecords: [
+    {
+      bIsEnabled: true,
+      nRevision: 0,
+      strId: 'record-1',
+      strName: '示例记录',
+    },
+  ],
+})
+```
+
+Demo Adapter 支持分页、关键字、取消、404 和基于 `nExpectedRevision` 的 409 冲突；更新只
+修改自身闭包数据，刷新后恢复初始值。Connected Adapter 依赖后端完成最终授权、事务和
+版本检查。
+
+## Query 与 Mutation
+
+列表和详情 Hook 只接收组合好的 Feature 运行实例，并自动复用应用级用户、租户、语言、
+会话版本和工作空间 Query 作用域：
+
+```tsx
+const objListQuery = useTemplateRecordList({
+  objFeature: objRecordFeature,
+  objInput: { nPage: 1, nPageSize: 20, strKeyword },
+  strWorkspaceId,
+})
+
+const objDetailQuery = useTemplateRecordDetail({
+  objFeature: objRecordFeature,
+  strRecordId,
+  strWorkspaceId,
+})
+```
+
+更新 Hook 绑定单个实体，因此同一实体 Mutation 串行、不同实体并行。详情存在缓存时执行
+可逆乐观更新；失败恢复快照；完成后用统一 Key 失效详情和列表。按钮仍应使用
+`objMutation.isPending` 防止用户无意重复激活：
+
+```tsx
+const objMutation = useUpdateTemplateRecord({
+  objFeature: objRecordFeature,
+  strRecordId,
+  strWorkspaceId,
+})
+
+objMutation.mutate({
+  nExpectedRevision: objDetailQuery.data.nRevision,
+  objChanges: { strName: '新名称' },
+})
+```
+
+Query 取消信号会一直传到生成客户端。Mutation 一旦到达服务端默认不假设可取消；具有
+重复副作用风险的命令使用
+[`mutation-idempotency.md`](mutation-idempotency.md) 的原键重试与结果确认协议，不能由
+本地缓存替代。
+
+页面首次加载、成功空态、错误恢复、后台刷新及 Toast 归属规则见
+[`page-feedback.md`](page-feedback.md)。列表和详情请求由页面内错误态负责时，Connected
+Source 必须传入 `bShowError: false`，避免统一响应 Hook 和页面重复提示同一次失败。
+
+## 模板明确不做的事
+
+- 不注册示例路由、菜单、页面或产品数据。
+- 不提供全局 Repository 容器、Service Locator 或万能 CRUD 配置。
+- 不要求所有 Feature 都拥有列表、详情和乐观更新；按真实工作流删减。
+- 不将客户端权限检查当作后端授权。
+- 不在 Connected 失败时显示 Demo 数据。
+- 不让其他 Feature 导入 `model.ts`、`repository.ts` 或 `queries.ts` 内部路径。
+
+模板契约测试位于 `tests/unit/scaffoldFeatureTemplate`，覆盖 DTO 拒绝、双 Adapter、取消、
+版本冲突、权限阻断、作用域 Key 以及 Mutation 后列表/详情缓存收敛。

package/template/docs/feature-flags.md

@@ -0,0 +1,169 @@
+# Feature Flag、灰度与 Kill Switch 接入
+
+`src/featureFlags` 提供厂商中立的 Feature Flag 运行时边界。它解决的是应用如何
+声明开关、隔离缓存、消费后端已评估结果，以及远端不可用时如何安全降级；不在
+浏览器中实现百分比、人群、权限或租户灰度规则。
+
+## 职责边界
+
+| 层级                   | 负责内容                                                  | 不负责内容                     |
+| ---------------------- | --------------------------------------------------------- | ------------------------------ |
+| 后端 Feature Flag 服务 | 规则、人群、百分比、租户和权限判断，返回已评估结果        | 前端展示                       |
+| 项目 Adapter           | 用 Swagger 生成客户端请求接口，并映射成脚手架目录契约     | 重新实现请求客户端             |
+| `src/featureFlags`     | 本地定义、安全默认、作用域缓存、有效期、刷新和 React 接入 | 权威鉴权、业务规则             |
+| Feature                | 根据评估结果控制入口、流程与回退体验                      | 拼接远端规则或直接调用厂商 SDK |
+
+Feature Flag 只影响前端呈现和行为。敏感数据、接口权限和操作合法性仍必须由后端
+授权。浏览器不得接收完整灰度规则、用户画像、Token 或供应商管理密钥。
+
+## 声明本地安全策略
+
+应用只请求显式声明的 Key。未知 Key 会立即抛出 `FeatureFlagError`，避免拼写错误
+静默变成关闭状态。
+
+```ts
+import type { IFeatureFlagDefinition } from '@/featureFlags'
+
+export const arrFeatureFlagDefinitions: readonly IFeatureFlagDefinition[] = [
+  {
+    bSafeDefault: false,
+    strKey: 'orders.bulkExport',
+    strKind: 'killSwitch',
+  },
+  {
+    bAllowStale: true,
+    bSafeDefault: false,
+    nMaxStaleMs: 5 * 60_000,
+    strKey: 'navigation.newShell',
+    strKind: 'release',
+  },
+]
+```
+
+三种用途的约束如下：
+
+- `killSwitch`：用于高风险能力，强制 `bSafeDefault: false`，禁止使用过期结果。
+- `release`：用于渐进发布；只有显式配置 `bAllowStale` 和有限
+  `nMaxStaleMs` 才能短暂使用最近结果。
+- `experiment`：用于服务端已完成分组的实验，可读取 `strVariant` 和
+  `objPayload`，前端不自行分桶。
+
+## 对接 Swagger 生成客户端
+
+`fnCreateFeatureFlagSource` 接收项目 Adapter 请求函数。下面仅展示映射位置，实际
+方法名和响应字段以生成代码为准：
+
+```ts
+import { fnCreateFeatureFlagSource } from '@/featureFlags'
+import { objGeneratedApi } from '@/api/generated/project'
+
+export const objFeatureFlagSource = fnCreateFeatureFlagSource(
+  async ({ arrFlagKeys, objScope, objSignal }) => {
+    const objResponse = await objGeneratedApi.featureFlags.evaluate(
+      {
+        environment: objScope.strEnvironment,
+        keys: arrFlagKeys,
+        sessionGeneration: objScope.nSessionGeneration,
+        tenantId: objScope.strTenantId,
+        userId: objScope.strUserId,
+        workspaceId: objScope.strWorkspaceId,
+      },
+      { signal: objSignal }
+    )
+
+    return {
+      nEvaluatedAt: objResponse.data.evaluatedAt,
+      nExpiresAt: objResponse.data.expiresAt,
+      objFlags: Object.fromEntries(
+        objResponse.data.flags.map((objFlag) => [
+          objFlag.key,
+          {
+            bEnabled: objFlag.enabled,
+            objPayload: objFlag.payload,
+            strReason: objFlag.reason,
+            strVariant: objFlag.variant,
+          },
+        ])
+      ),
+      version: objResponse.data.version,
+    }
+  }
+)
+```
+
+Adapter 返回值会做运行时校验并深度冻结。时间戳必须是有限的毫秒值，且
+`nExpiresAt` 必须晚于 `nEvaluatedAt`。请求取消通过 `objSignal` 传给生成客户端。
+
+## 应用装配
+
+这是按需能力，默认 `Application` 不装配 Provider。项目应在需要开关的认证布局或 Feature
+边界挂载，并从现有查询作用域补充用户、租户、工作空间和会话隔离信息：
+
+```tsx
+const objQueryScope = useAppQueryScope()
+
+<FeatureFlagProvider
+  arrDefinitions={arrFeatureFlagDefinitions}
+  bIsEnabled={bIsAuthenticated}
+  objScope={{
+    strEnvironment: 'production',
+    nSessionGeneration: objQueryScope.nSessionGeneration,
+    strTenantId: objQueryScope.strTenantId,
+    strUserId: objQueryScope.strUserId,
+    strWorkspaceId: objQueryScope.strWorkspaceId,
+  }}
+  objSource={objFeatureFlagSource}
+>
+  {objChildren}
+</FeatureFlagProvider>
+```
+
+未配置数据源、关闭远端能力、首次加载和请求失败都不会阻塞子树渲染，而是立即返回本地
+安全默认值。匿名页面确实需要开关时，可以在公开页面边界单独挂载并提供匿名作用域；不要
+为了少写一层 Provider 把它重新塞回全局 `Application`。
+
+## Feature 消费
+
+```tsx
+import { FeatureGate, useFeatureFlag } from '@/featureFlags'
+
+function ExportEntry() {
+  const objFlag = useFeatureFlag('orders.bulkExport')
+
+  return (
+    <FeatureGate
+      objFallback={<p>批量导出暂不可用</p>}
+      strFlagKey="orders.bulkExport"
+    >
+      <ExportButton strVariant={objFlag.strVariant} />
+    </FeatureGate>
+  )
+}
+```
+
+`bEnabled` 是最终状态；`bIsFallback`、`strEvaluationSource`、
+`strEvaluationReason` 和 `strVersion` 用于非敏感诊断。长任务不能只隐藏入口：
+Feature 还应在开关关闭时取消尚未提交的前端工作，后端必须独立拒绝已关闭的危险
+操作。
+
+## 缓存、刷新与降级
+
+- 缓存仅保存在现有 React Query 内存缓存中，不写 `localStorage`，避免跨用户泄漏。
+- Query Key 包含环境、用户、租户、工作空间、会话代次和排序后的声明 Key。
+- 目录按后端 `nExpiresAt` 自动刷新；失败后以一分钟间隔恢复请求。
+- 新作用域会取消或隔离旧请求；登出、租户切换和会话代次变化不会复用旧身份结果。
+- Kill Switch 过期立即关闭。其他类型只有声明了有限 stale 窗口才可继续使用旧值。
+- `fnInvalidateFeatureFlags` 用于管理操作、会话变化或项目事件触发主动失效；
+  `fnEnsureFeatureFlags` 和 `fnGetCachedFeatureFlags` 支持 Loader 场景。
+
+不要把“最后一次成功结果”永久持久化。离线持久化涉及用户身份、敏感配置和撤销
+时效，属于 P2-08 的独立策略，不由本模块隐式开启。
+
+## 验收重点
+
+- 无数据源和请求失败时，所有已声明开关都有确定的本地结果。
+- Kill Switch 无法配置为默认开启，也无法允许过期结果。
+- 远端目录、单项值、有效期和 JSON Payload 都经过运行时校验。
+- 不同用户、租户、工作空间、会话代次和环境不会共享缓存。
+- React 消费者共享同一请求，远端失败不阻塞应用子树。
+- 前端没有人群规则、权限替代逻辑、厂商密钥和业务页面。