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

package/template/docs/authentication-adapters.md

@@ -0,0 +1,219 @@
+# SSO、MFA 与 Step-up 认证 Adapter
+
+P2-01 为企业项目提供供应商无关的认证编排边界。默认 core 保留现有账号密码登录、Token
+刷新、权限快照、退出撤销和路由失效生命周期；需要 OIDC、SAML 网关、企业统一身份、MFA
+或敏感操作 Step-up 时，先添加 `advancedAuthentication` 能力，再通过生成客户端 Adapter
+接入。
+
+```bash
+pnpm scaffold:add --target <项目目录> --capability advancedAuthentication
+```
+
+它不内置某个身份供应商 SDK、登录按钮、回调地址或 MFA 页面。没有真实项目配置时，不把
+协议依赖、供应商品牌或业务权限码放进默认首屏。
+
+## 责任边界
+
+| 层级                    | 负责内容                                                         |
+| ----------------------- | ---------------------------------------------------------------- |
+| 身份服务/后端           | 协议交换、state/nonce/PKCE 校验、MFA、租户和账号授权、会话与审计 |
+| 生成客户端 Adapter      | 将 OpenAPI DTO 映射为 redirect/challenge/complete 稳定结果       |
+| `authentication` 控制器 | 竞态取消、状态编排、跳转白名单、完成结果即时消费和安全错误       |
+| 应用认证会话            | Token 生命周期、用户权限快照、刷新、退出、缓存和路由失效         |
+| 登录/回调/挑战 Feature  | 展示、表单、焦点、错误反馈和站内安全导航                         |
+
+前端隐藏按钮和路由守卫不是授权。后端必须对登录、回调、挑战验证、Step-up 目标操作和跨租户资源
+重新授权。推荐由服务端会话承载 Step-up 结果；必须返回短期证明时，它只能进入紧随其后的目标
+请求，不能进入 URL、Store、本地存储、日志、监控或错误文案。
+
+## 公共入口
+
+从 `@/authentication` 导入：
+
+- `fnCreateAuthenticationController()`：统一编排登录、回调、MFA 和 Step-up。
+- `fnResolveAuthenticationRedirect()`：校验 HTTP(S)、凭据、Fragment 和 Origin 白名单。
+- `IAuthenticationAdapter`：由 Feature 使用生成客户端实现的协议边界。
+- `TAuthenticationAdapterResult`：`redirect`、`challenge`、`complete` 互斥结果。
+- `TAuthenticationCompletion`：登录 Token 结果或 Step-up 短期授权。
+- `AuthenticationError`：不包含协议参数、Token 或挑战响应的稳定错误。
+
+`fnCreateAuthenticationController()` 的返回值已经保留完整类型推导，业务通常不需要显式导入
+控制器、快照和启动参数等叶子类型。
+
+## 生成客户端 Adapter
+
+`swagger-typescript-api` 生成目录只保存后端契约，不能手工修改。Feature 在生成客户端之上
+做一次窄映射，页面和控制器不判断 OIDC、SAML 或供应商响应字段：
+
+```ts
+const objAuthenticationAdapter: IAuthenticationAdapter = {
+  async fnStart(objInput, { objSignal }) {
+    const objResponse = await objGeneratedAuthApi.authentication.start(
+      {
+        actionKey:
+          objInput.strPurpose === 'stepUp'
+            ? objInput.strActionKey
+            : undefined,
+        providerKey: objInput.strProviderKey,
+        purpose: objInput.strPurpose,
+        returnPath:
+          objInput.strPurpose === 'signIn'
+            ? objInput.strReturnPath
+            : undefined,
+      },
+      { signal: objSignal }
+    )
+    return fnMapAuthenticationResult(objResponse.data)
+  },
+  async fnCompleteRedirect(objInput, { objSignal }) {
+    const objResponse = await objGeneratedAuthApi.authentication.callback(
+      {
+        parameters: objInput.objParameters,
+        purpose: objInput.strPurpose,
+      },
+      { signal: objSignal }
+    )
+    return fnMapAuthenticationResult(objResponse.data)
+  },
+  async fnVerifyChallenge(objInput, { objSignal }) {
+    const objResponse = await objGeneratedAuthApi.authentication.verify(
+      {
+        challengeId: objInput.strChallengeId,
+        method: objInput.strMethod,
+        response: objInput.objResponse,
+      },
+      { signal: objSignal }
+    )
+    return fnMapAuthenticationResult(objResponse.data)
+  },
+}
+```
+
+示例方法名以项目 OpenAPI 为准。`fnMapAuthenticationResult()` 是 Adapter 私有的运行时校验
+边界：拒绝未知状态、空事务标识、无效过期时间和缺失 Token。控制器会继续执行第二层稳定
+合同校验，但不能代替网络响应 Schema 校验。
+
+## 创建控制器
+
+外部身份提供方 Origin 必须来自已校验的项目运行时公开配置。当前应用 Origin 自动允许；
+外部 HTTP、未知 Origin、URL 凭据、Fragment Token 和非 HTTP(S) 协议会被拒绝：
+
+```ts
+const objAuthenticationController = fnCreateAuthenticationController({
+  objAdapter: objAuthenticationAdapter,
+  objRedirectPolicy: {
+    strApplicationOrigin: globalThis.location.origin,
+    arrAllowedOrigins: ['https://identity.example.com'],
+  },
+  fnNavigateRedirect: (strRedirectUrl) => {
+    globalThis.location.assign(strRedirectUrl)
+  },
+  async fnOnComplete(objCompletion, { objSignal }) {
+    if (objSignal.aborted) return
+    if (objCompletion.strPurpose === 'signIn') {
+      await fnEstablishAuthSessionFromToken(
+        objCompletion.objTokenResult,
+        ''
+      )
+      await fnNavigate({
+        href: fnGetPostSignInPath(objCompletion.strReturnPath),
+        replace: true,
+      })
+      return
+    }
+
+    await fnResumePendingSensitiveOperation(
+      objCompletion.objGrant,
+      objSignal
+    )
+  },
+})
+```
+
+完成结果会在 `fnOnComplete` 中立即消费，不进入可订阅快照。SSO、MFA 和账号密码最终都调用
+`fnEstablishAuthSessionFromToken()`，因此不会产生第二套 Token Store、刷新锁或权限来源。
+Step-up 完成后只恢复当前挂起操作；恢复请求必须使用完成回调提供的 `AbortSignal`。如果操作
+已经取消、资源已变化或授权过期，应丢弃结果并要求重新确认。
+
+## 登录与回调流程
+
+登录按钮只提供后端配置的 `strProviderKey`，不自行拼授权地址：
+
+```ts
+await objAuthenticationController.fnStart({
+  strProviderKey: 'corporate-sso',
+  strPurpose: 'signIn',
+  strReturnPath: '/orders',
+})
+```
+
+控制器会先校验 `strReturnPath` 是站内绝对路径，再交给 Adapter。后端必须把回跳路径与一次性
+state 事务绑定，不能直接相信回调查询参数。
+
+完整页面跳转后，新的回调页面创建同样的控制器，并只把路由白名单允许的字符串参数交给
+Adapter：
+
+```ts
+await objAuthenticationController.fnCompleteRedirect({
+  strPurpose: 'signIn',
+  objParameters: {
+    code: objSearch.code,
+    state: objSearch.state,
+  },
+})
+```
+
+回调路由必须分别确定 `signIn` 或 `stepUp` purpose，不允许查询参数自行声明。回调错误描述
+只交给 Adapter 和后端分类，不能原样写入监控或全局错误提示。
+
+## MFA 与 Step-up
+
+Adapter 返回 `challenge` 后，快照进入 `awaitingChallenge` 并只保存挑战标识、方式、过期时间、
+剩余次数和后端脱敏目标。OTP、恢复码和 WebAuthn 响应只存在于表单草稿及本次 Adapter 请求：
+
+```ts
+await objAuthenticationController.fnVerifyChallenge({
+  strChallengeId: objSnapshot.objChallenge.strChallengeId,
+  strMethod: objSnapshot.objChallenge.strMethod,
+  objResponse: { code: strOtpCode },
+})
+```
+
+敏感数据显示、批量高风险操作或账户安全设置可以启动 Step-up：
+
+```ts
+await objAuthenticationController.fnStart({
+  strActionKey: 'customer:identity:reveal',
+  strProviderKey: 'corporate-mfa',
+  strPurpose: 'stepUp',
+  strResourceKey: 'customer',
+})
+```
+
+`strActionKey` 是后端稳定操作码，`strResourceKey` 只能表达资源类型或范围，不能把手机号、
+证件号、订单内容等个人数据放入认证事务、URL 或日志。真正目标资源 ID 和 Step-up 授权由
+后续敏感请求在后端共同校验。
+
+## 生命周期和失败策略
+
+- 新的 start、callback 或 challenge 请求会取消旧请求，晚到结果不能覆盖当前状态。
+- `fnCancel()` 先清除本地挑战和请求，再尽力取消后端事务；远端失败不会恢复本地状态。
+- `fnReset()` 只清除控制器展示状态，不撤销登录会话或服务端授权。
+- 控制器快照不保存 Token、Step-up Proof、OTP、回调参数或完整跳转 URL。
+- 登录完成回调失败时不能建立半个会话；现有会话函数负责身份结果校验和缺失身份时的 Token
+  撤销。具体应用准入由后端和权限码决定，前端不硬编码角色字符串。
+- 浏览器离开挑战页面时应调用 `fnCancel()`；登录回调和 Step-up 恢复动作应具备幂等性。
+
+如果项目使用自动携带 Cookie 的 BFF，会话 Cookie 的 `HttpOnly`、`Secure`、`SameSite` 和
+CSRF 防护全部由服务端负责。前端不能通过读取 Cookie 来推断或模拟这些属性。
+
+## 验收清单
+
+- 页面不拼接 OIDC/SAML 地址，也不解析供应商 DTO；协议逻辑只存在于 Adapter 和后端。
+- 外部跳转只允许显式 HTTPS Origin；未知 Origin、凭据、Fragment 和危险协议被拒绝。
+- 登录回跳路径必须是站内绝对路径，并与服务端一次性 state 事务绑定。
+- 账号密码、SSO 和 MFA 完成后使用同一会话、刷新锁、权限快照和退出流程。
+- MFA/Step-up 挑战、取消、过期、重复提交、晚到响应和远端取消失败都有稳定状态。
+- Step-up 不创建第二套登录会话，短期证明不进入 Store、URL、存储、日志或监控。
+- Adapter 使用生成客户端并传递 AbortSignal；生成目录没有手工业务修改。
+- 不安装未选定的身份供应商 SDK，不把可选认证能力打进默认首屏。

package/template/docs/browser-security.md

@@ -0,0 +1,58 @@
+# 浏览器安全基线
+
+脚手架把浏览器安全拆成三条可验证边界：构建依赖必须通过漏洞审计，静态站点必须返回固定
+安全响应头，业务接入不得绕过浏览器与服务端各自的授权责任。前端权限只控制展示，最终
+认证、租户隔离和资源授权仍由后端执行。
+
+## 默认响应头
+
+`deploy/nginx.conf` 为所有响应设置以下策略：
+
+- CSP 默认只允许同源资源，禁止插件对象、内联脚本、事件属性脚本和第三方页面嵌入；
+- 图片与受沙箱约束的文件预览允许 `blob:`，图片额外允许公开 HTTPS 和 Data URL；
+- `X-Frame-Options: DENY` 为旧浏览器补充点击劫持防护；
+- HSTS、`nosniff` 和严格来源策略减少降级、类型混淆和跨站来源泄露；
+- COOP/CORP 默认保持同源隔离；Permissions Policy 关闭摄像头、定位、麦克风、支付和 USB。
+
+`style-src 'unsafe-inline'` 是当前 React 组件内联样式和第三方 UI 兼容边界，不适用于脚本。
+如要移除它，应先验证全部组件状态和动态定位能力，不能直接修改生产头部碰运气。
+
+生产 API 推荐由宿主机 `/api/` 反向代理保持同源。若项目确实需要跨域 API、字体、图片或
+Office 预览服务，应同时完成以下工作：
+
+1. 将明确的 Origin 加入 CSP 对应指令，不使用 `*`；
+2. 在文件预览 Adapter 的 `arrAllowedOrigins` 中加入相同 Origin；
+3. 配置后端 CORS、认证凭据和请求 ID 暴露头；
+4. 更新 `deployConfig.test.mjs` 中的 CSP 期望值并说明新增数据边界；
+5. 先通过 Report-Only 在目标环境观察，再切换为强制策略。
+
+## 依赖审计
+
+执行：
+
+```bash
+pnpm security:audit
+```
+
+main 分支封装发布制品前，GitLab CI 会审计生产及开发依赖，发现 High 或 Critical 已知漏洞
+即失败。构建工具同样纳入审计，因为受污染的开发依赖可以改变最终静态产物。
+
+处理告警时优先升级直接依赖，其次使用带有明确影响分析的 `pnpm.overrides`。不得通过
+`--ignore-registry-errors` 放过 Registry 故障；确需接受风险时，应在项目安全记录中写明
+GHSA、不可利用的证据、负责人和到期日，而不是永久降低全局阈值。
+
+## CSP 变更门禁
+
+`tests/unit/config/deployConfig.test.mjs` 会完整比较 CSP，并禁止脚本使用 `unsafe-inline` 或
+`unsafe-eval`。任何修改都必须同时评审允许的数据来源、浏览器能力、用户信息暴露面和回滚
+方案。供应商 SDK 不能因为“监控需要”直接获得任意 `connect-src`、脚本或用户数据权限。
+
+部署后至少检查：
+
+```bash
+curl -sSI https://admin.example.com/sign-in
+curl -sSI https://admin.example.com/runtime-config.json
+```
+
+确认安全头存在，`runtime-config.json` 为 `no-store`，并在浏览器 DevTools 中检查没有意外
+CSP 违规。CSP 是纵深防御，不替代安全 DOM API、输入输出校验和服务端授权。

package/template/docs/bundle-budgets.md

@@ -0,0 +1,65 @@
+# 构建体积预算
+
+构建体积预算用于阻止默认入口和关键用户旅程在没有明确决策的情况下持续膨胀。它是稳定的
+实验室门禁，不替代真实用户的 Web Vitals、网络瀑布、缓存命中率或低端设备性能数据。
+
+## 当前预算
+
+`tools/bundle/budgets.json` 是唯一预算来源。当前基线使用 Node `zlib` level 9 对生产文件
+执行 gzip，并按 Vite Manifest 的静态 `imports` 递归去重：
+
+| 预算 ID         | 用户旅程/资源              | 当前基线   | 上限    | Owner                    |
+| --------------- | -------------------------- | ---------- | ------- | ------------------------ |
+| `bootstrap-js`  | 加载应用入口和运行时配置   | 79.75 KiB  | 84 KiB  | 应用入口与运行时配置     |
+| `sign-in-js`    | 启动应用并进入登录 Feature | 191.75 KiB | 205 KiB | 认证 Feature 与访客路由  |
+| `dashboard-js`  | 启动应用并进入中性首页     | 222.36 KiB | 238 KiB | 认证后壳层与首页 Feature |
+| `bootstrap-css` | 入口声明的全局样式         | 15.33 KiB  | 18 KiB  | 全局样式与主题           |
+
+基线记录的是本次建立门禁时的受控生产构建，不承诺所有 Node/zlib 版本逐字节一致；预算已保留
+约 5% 到 17% 的工具链和正常小改动余量。字体、图片和其他静态资源不计入 JavaScript/CSS
+预算，也不能因此忽略：若它们影响真实页面，应建立对应资源或请求预算。
+
+## 执行方式
+
+```bash
+pnpm build
+```
+
+`vite build` 会生成内部 `.vite/manifest.json`，随后 `pnpm bundle:check` 校验四项预算。
+Manifest 仅用于构建分析，`pnpm release:prepare` 会把它和环境专属
+`runtime-config.json` 一起排除在不可变发布站点之外。
+
+已有同一 Commit 的完整 `dist` 时，也可以单独复查：
+
+```bash
+pnpm bundle:check
+```
+
+不得用旧 `dist` 代表当前源码。预算检查找不到 Manifest、入口、静态依赖或普通产物文件时
+会直接失败，不会以 `0 KiB` 误报通过。
+
+## 预算语义
+
+- `arrEntries` 表示完成该旅程必须获取的入口集合；每个入口的静态依赖递归计入并按产物
+  路径去重。
+- 动态依赖只有在成为该旅程的显式入口时才计入。例如登录页计入 Auth Feature，中性首页
+  计入 AppLayout 与 Home Feature，但 Web Vitals 和未访问错误页不会被误算到同一路径。
+- CSS 预算读取入口静态图中的 `css` 文件；不会把 JavaScript、字体和图片混在一起。
+- 超限诊断按 gzip 体积列出最大的五个 Chunk、Manifest Owner 和文件路径，Owner 是责任
+  边界，不表示某个开发者个人。
+
+## 调整规则
+
+预算超限时优先检查诊断中最大的 Chunk 及最近新增静态依赖，将仅特定路由或可选交互使用的
+能力保持在动态边界。不要为了过门禁立即提高阈值，也不要为了减少单个 Chunk 数字制造大量
+无意义请求。
+
+确实需要提高预算时，同一个变更必须记录：
+
+1. 哪个真实用户旅程获得了什么能力。
+2. 调整前后 gzip 体积和主要 Chunk 归属。
+3. 为什么不能放入既有路由或可选能力的动态边界。
+4. 低端设备、弱网或生产 Web Vitals 的补充证据与回滚方式。
+
+新的关键路由应新增独立旅程预算，而不是扩大 `dashboard-js` 代替。大型编辑器、地图、报表
+和高级表格等可选能力按自己的用户路径评估，不能因为它们合法按需加载就进入默认入口。

package/template/docs/component-source-governance.md

@@ -0,0 +1,99 @@
+# 内建组件源码治理
+
+## 单一事实源
+
+`AppPageForm` 与 `AppTable` 来自团队内部仓库的固定源码快照，不再作为私有 Node 包安装。
+来源 repository、完整 revision、包版本、导入日期、选择性同步范围、本地改造、回归证据和
+第三方许可证期望只记录在
+[`tools/component-governance/manifest.json`](../tools/component-governance/manifest.json)。
+各组件的 `SOURCE.md` 只解释目录改造和接入边界，不再重复保存 revision。
+
+两个内部来源在已记录 revision 都没有 `LICENSE` 或 `NOTICE`。因此清单强制
+`internal-only`：在取得书面代码权属与再分发授权前，不得公开发布、出售或复制到外部
+仓库。工程门禁不能代替法务审核。
+
+## 持续检查
+
+```bash
+pnpm components:check
+```
+
+该命令已经进入 `pnpm verify` 和 GitLab verify Job，会同时验证：
+
+1. 清单结构、完整 40 位 revision、内部源码分发状态和不重复的组件记录。
+2. 本地源码目录、公共入口、`SOURCE.md`、回归测试文件和必跑命令仍然存在。
+3. `SOURCE.md` 指向唯一清单且没有复制 revision；业务仍通过 `AppPageForm`、`AppTable`
+   公共入口消费。
+4. `package.json`/锁文件没有重新引入内部 Git 包。
+5. Handsontable、ExcelJS 的安装版本、`package.json#license` 和实际许可证文件与清单一致。
+6. Handsontable 商业 Key、首屏按需加载等策略标记仍有构建实现和测试证据。
+
+依赖升级导致版本或许可证文本变化时，检查会失败并要求人工复核，不会自动接受新条款。
+ESLint 的 `project-naming/component-boundaries` 同时禁止 `src` 中的外部消费者深层导入两个
+内建组件；组件内部可以继续按领域目录组织，组件外只能使用根 `index.ts` 公共入口。
+
+## 查看升级候选
+
+来源仓库必须是正确 origin、干净工作区，并且候选 HEAD 必须是已记录 revision 的后继。
+工具只读取 Git 历史，不访问网络，也不修改来源仓库、本项目源码或清单。
+
+```bash
+pnpm components:diff -- \
+  --component AppPageForm \
+  --source-root /absolute/path/to/page-form
+
+pnpm components:diff -- \
+  --component AppTable \
+  --source-root /absolute/path/to/table-component
+```
+
+输出仅包含清单 `includedPaths` 范围内的 `A/M/D/R` 文件列表、基准/候选 revision、许可证
+文件集合变化和必跑回归证据。它不会声称候选已经兼容本项目。
+
+常见失败诊断：
+
+| 错误码                                 | 含义                         | 处理方式                                     |
+| -------------------------------------- | ---------------------------- | -------------------------------------------- |
+| `COMPONENT_SOURCE_DIRTY`               | 来源仓库存在未提交修改       | 提交、切走或恢复后重新执行                   |
+| `COMPONENT_SOURCE_REPOSITORY_MISMATCH` | origin 不是清单登记仓库      | 切换到正确内部来源仓库                       |
+| `COMPONENT_SOURCE_REVISION_NOT_FOUND`  | 基准 revision 不在本地历史   | `git fetch --all --prune` 后核对清单         |
+| `COMPONENT_SOURCE_HISTORY_DIVERGED`    | 候选不是基准的前向升级       | 切换到正式升级分支，不得整目录覆盖           |
+| `COMPONENT_SOURCE_LICENSE_CHANGED`     | LICENSE/NOTICE 文件集合变化  | 暂停同步并完成权属、许可证和再分发评审       |
+| `COMPONENT_DEPENDENCY_LICENSE_DRIFT`   | 第三方包声明的许可证发生变化 | 暂停发布，检查新版本许可证文本与 NOTICE 义务 |
+| `COMPONENT_GOVERNANCE_GATE_MISSING`    | 检查未进入 `verify`          | 恢复 package scripts，不允许仅靠人工记忆执行 |
+
+## 选择性同步流程
+
+1. 在来源仓库执行 `git fetch`，切换到干净且已提交的候选 revision。
+2. 执行 `components:diff`，评审 engine/core、React 渲染、公共类型和许可证变化。
+3. 只移植当前应用需要的行为；继续排除 Vue、示例、发布配置、仓库工具和重复 UI primitives。
+4. 保留本项目的公共入口、目录边界、Locale、权限、未保存保护和全局 UI 组件；禁止无审计的
+   整目录覆盖。
+5. 公共属性、类型、焦点行为、CSS Token 或校验语义发生变化时，按破坏性变更处理，并在
+   同一评审中提供迁移说明和消费者回归测试。
+6. 完成源码移植和行为测试后，才更新清单的 revision、包版本与导入日期；不要提前移动
+   基准，否则差异工具会丢失未同步变化。
+7. 执行清单列出的定向测试、`pnpm components:check` 和 `pnpm verify`，由评审者核对最终
+   Diff 与升级候选一致。
+8. 同步失败时回退本次选择性移植和清单修改；原 revision 始终是可恢复基线。
+
+## 第三方边界
+
+- `AppTable` 依赖 Handsontable。评估许可证只能用于评估；只有最终产物包含 `AppTable`
+  时，生产部署才必须注入项目获得的商业 Key。构建拒绝缺失/评估 Key 和首屏静态引入，
+  但 Key 的项目范围、有效期和版本权利仍需采购与交付记录确认。
+- Excel 导出依赖 ExcelJS。发布产物和归档材料必须按其许可证要求保留许可证文本；升级时
+  以实际安装包而不是记忆中的许可证类型为准。
+- `components/ui` 是唯一全局 UI primitives，来源同步不得复制上游 shadcn 文件或 `cn`
+  helper。
+- 外部分发前必须同时确认本仓库许可证、两个内部源码的书面授权及全部运行时依赖义务。
+
+## AppTable 构建约束
+
+- 普通列表使用 `AppDataTable`，不为基础场景引入 Handsontable。
+- `AppTable` 只能从 `@/components/AppTable` 公共入口导入，并由按需加载的 Feature 使用。
+- Vite 根据最终 Rollup 模块图判断高级表格是否进入产物；未使用时不要求商业 Key，也不
+  生成 Handsontable Chunk。
+- Handsontable 固定在 `advanced-table-vendor` 异步 Chunk。缺少许可证时报
+  `APP_TABLE_LICENSE_REQUIRED`，进入入口静态依赖闭包时报 `APP_TABLE_EAGER_LOAD`；错误
+  信息不会回显 Key。

package/template/docs/data-masking.md

@@ -0,0 +1,169 @@
+# 数据脱敏展示
+
+数据脱敏能力用于客户列表、员工档案、订单联系人、财务账户和审计详情等场景。脚手架提供
+统一脱敏策略、安全展示组件及 AppTable 敏感列工厂，不内置任何业务字段、权限码或查看
+接口。
+
+## 安全边界
+
+前端脱敏只是展示保护，不能替代后端数据权限。接口应按最小化原则返回数据：没有原始值
+权限时，列表和详情 DTO 只返回后端生成的 `strMaskedValue`，不应把原始值传给浏览器再用
+CSS、星号或隐藏按钮遮住。临时查看接口必须再次校验用户、租户、记录范围、字段权限及
+必要的 Step-up 状态，并在服务端完成审计。
+
+查看和复制是两个独立操作：拥有查看权限不自动获得复制原始值权限。组件默认不展示查看
+入口，也默认不允许复制；业务必须显式配置对应策略。原始值不会进入 DOM 属性、错误文案、
+本地存储或可观测性事件，离开页面、切换后台、权限撤销、组件卸载和超时都会自动回掩。
+
+`src/observability/redaction.ts` 负责日志和遥测边界的兜底清洗，与本模块的界面展示策略职责
+不同。两者不能互相替代。
+
+## 公共入口
+
+从 `@/dataMasking` 导入：
+
+- `fnMaskSensitiveText()`：按常见预设或字段级覆盖生成脱敏文本。
+- `fnResolveSensitiveDataMaskedText()`：优先使用后端脱敏值，仅在原始值存在时前端计算。
+- `objDataMaskingPresets`：手机号、证件号、银行卡、姓名、邮箱和通用分段默认策略。
+- `TSensitiveDataValue`：区分浏览器只有脱敏值和已经持有原始值的互斥 DTO 形态。
+- `TSensitiveDataRevealPolicy` / `TSensitiveDataCopyPolicy`：查看与复制的组合策略类型。
+- `SensitiveDataError`：不携带原始值的稳定查看/复制错误。
+
+从 `@/components/SensitiveData` 导入 `SensitiveData`。从
+`@/components/AppTable` 导入 `fnCreateSensitiveDataTableColumn()`，用于固定关闭表格原生复制
+和编辑旁路。
+
+## 基础展示
+
+后端已按当前用户权限返回脱敏文本时，优先使用 `masked` 形态：
+
+```tsx
+<SensitiveData
+  objMaskingPolicy={{ strPreset: 'phone' }}
+  objValue={{
+    strMaskedValue: objCustomer.strMaskedPhone,
+    strState: 'masked',
+  }}
+  strLabel='手机号'
+/>
+```
+
+如果详情接口已经授权并返回原始值，可以使用 `available` 形态；组件仍默认脱敏展示：
+
+```tsx
+<SensitiveData
+  objMaskingPolicy={{ strPreset: 'identity' }}
+  objValue={{
+    strState: 'available',
+    strValue: objEmployee.strIdentityNumber,
+  }}
+  strLabel='证件号'
+/>
+```
+
+内建预设是脚手架默认值，不代表所有国家、证件或账户格式。项目可通过
+`nVisibleStart`、`nVisibleEnd`、`nMaskLength` 和 `strMaskCharacter` 做字段级调整。固定
+`nMaskLength` 可以避免通过星号数量泄露原始长度。
+
+## 通过生成客户端按需查看
+
+`swagger-typescript-api` 生成目录仍然只保存后端契约，不手工修改。拥有业务语义的 Feature
+创建轻量 Adapter，把生成方法的 DTO 映射为组件需要的原始字符串，并传递取消信号：
+
+```tsx
+const fnRequestPhoneReveal: TSensitiveDataRevealAdapter = async ({
+  objSignal,
+}) => {
+  const objResponse = await objGeneratedApi.customer.revealPhone(
+    objCustomer.strId,
+    { signal: objSignal }
+  )
+  return objResponse.data.strPhone
+}
+
+<SensitiveData
+  fnRequestReveal={fnRequestPhoneReveal}
+  objMaskingPolicy={{ strPreset: 'phone' }}
+  objRevealPolicy={{
+    nDurationMs: 30_000,
+    objRequirement: 'customer:phone:view',
+    strMode: 'authorized',
+  }}
+  objValue={{
+    strMaskedValue: objCustomer.strMaskedPhone,
+    strState: 'masked',
+  }}
+  strLabel='手机号'
+/>
+```
+
+示例中的生成方法名和参数以项目 OpenAPI 为准。Adapter 应位于 Feature 的 repository 或
+adapter 边界，不应在基础组件中导入某个业务服务的生成 `Api.ts`。取消、超时或权限变化后
+晚到的响应不会重新展示。
+
+## 复制策略
+
+只复制脱敏值时可以配置 `masked`；复制原始值必须配置 `revealed` 并提供不可省略的独立权限
+要求，而且复制按钮只会在原始值当前可见时出现：
+
+```tsx
+<SensitiveData
+  objCopyPolicy={{
+    objRequirement: 'customer:phone:copy',
+    strMode: 'revealed',
+  }}
+  objMaskingPolicy={{ strPreset: 'phone' }}
+  objRevealPolicy={{
+    objRequirement: 'customer:phone:view',
+    strMode: 'authorized',
+  }}
+  objValue={objSensitivePhone}
+  strLabel='手机号'
+/>
+```
+
+默认实现只使用安全上下文中的 Clipboard API，不使用遗留 `execCommand`。页面可以通过
+`fnWriteClipboard` 接入自己的浏览器兼容 Adapter，通过 `fnOnError` 显示统一反馈；任何反馈
+和日志都只能记录 `SensitiveDataError.strCode`，不能记录待复制文本。
+
+## AppTable 接入
+
+不能只把自定义 cellComponent 渲染成星号，因为 Handsontable 仍可能从底层数据复制原始值。
+敏感列必须使用安全列工厂：
+
+```tsx
+const objPhoneColumn = fnCreateSensitiveDataTableColumn<
+  ICustomerRow,
+  string
+>({
+  objColumn: {
+    key: 'strMaskedPhone',
+    label: '手机号',
+  },
+  fnResolveSensitiveDataProps: ({ row: objRow, value: strMaskedPhone }) => ({
+    fnRequestReveal: ({ objSignal }) =>
+      fnRevealCustomerPhone(objRow.strId, objSignal),
+    objMaskingPolicy: { strPreset: 'phone' },
+    objRevealPolicy: {
+      objRequirement: 'customer:phone:view',
+      strMode: 'authorized',
+    },
+    objValue: { strMaskedValue: strMaskedPhone, strState: 'masked' },
+  }),
+})
+```
+
+工厂强制 `readOnly: true`、`copyable: false` 和 `exportable: false`，因此客户端导出和
+远程导出元数据也不会包含该列。需要敏感字段导出时必须提供后端独立授权的专用导出接口，
+不能把列开关改回 true。最佳方案仍是让列表行只包含脱敏字段；如果原始值已经在行 DTO 中，
+关闭表格复制无法防止浏览器扩展、开发者工具或其他脚本读取。
+
+## 验收清单
+
+- 无查看权限时浏览器 DTO 不包含原始值，页面也不渲染查看入口。
+- 默认只展示后端脱敏值或前端预设结果，短值不会因为配置错误完整暴露。
+- 查看、复制脱敏值和复制原始值分别配置权限，复制原始值不能隐式触发查看。
+- 按需查看使用生成客户端 Adapter，支持取消，失败反馈和日志不包含原始值。
+- 超时、权限撤销、页面隐藏、离页和卸载后立即回掩并清除组件内临时值。
+- AppTable 敏感列固定只读并禁止原生复制和通用导出，敏感导出由后端单独授权。
+- 共享中英文文案和键盘可访问按钮均可工作。