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

package/template/docs/scaffold-capability-roadmap.md

@@ -0,0 +1,226 @@
+# 企业 React 脚手架能力路线图
+
+这份文档是脚手架建设的唯一能力台账，用于回答“还缺什么、先做什么、做到什么程度算
+完成”。`enterprise-scaffold.md` 继续描述架构原则，本文件负责交付状态和验收标准。
+
+## 状态说明
+
+| 状态        | 含义                                                    |
+| ----------- | ------------------------------------------------------- |
+| ✅ 已完成   | 已有实现、公共入口、测试或文档，能够直接被新项目使用    |
+| 🟡 部分完成 | 已有基础实现，但公共契约、场景覆盖或自动化验收不完整    |
+| 🚧 进行中   | 当前正在实现，合并且通过 `pnpm verify` 后才能改为已完成 |
+| ⬜ 待建设   | 属于企业脚手架基线，但尚未实现                          |
+| ⏸ 暂缓      | 当前阶段没有成立的业务或组织条件，触发条件成立后再评估  |
+| 🔌 按需接入 | 只提供接入边界或方案，不默认进入应用主包                |
+
+状态只能根据仓库中的可验证事实更新，不能因为文档写过或存在内部函数就标记完成。
+
+## 范围边界
+
+脚手架内置的是跨项目稳定复用的技术能力，不是具体产品。用户、角色、组织、审批、
+客户、供应商和业务报表等仍由项目自己的 Feature 实现。
+
+每项基线能力完成时至少满足：
+
+1. 有明确的公共入口、所有者和不支持范围。
+2. 覆盖加载、成功、空、失败、重试、取消或无权限等适用状态。
+3. 不把服务端数据复制到第二份全局状态，不在客户端承担最终授权。
+4. 有针对用户可见行为或公共契约的测试。
+5. 文档包含接入示例，并通过 `pnpm verify`。
+
+## P0：开箱即可开发和交付
+
+P0 是发布为企业脚手架前必须完成的基线。
+
+### 1. 应用边界与壳层
+
+| 编号  | 状态 | 能力                  | 完成标准                                                              |
+| ----- | ---- | --------------------- | --------------------------------------------------------------------- |
+| P0-01 | ✅   | 无业务语义的应用壳层  | 默认只有登录、中性首页和通用错误页；不包含系统管理或产品页面          |
+| P0-02 | ✅   | 弹性布局与导航        | 侧边栏、面包屑、菜单搜索、桌面窄窗口和路由元数据使用同一来源          |
+| P0-03 | ✅   | 品牌与主题            | 应用名称、Logo、浅色/深色主题和用户偏好集中配置并持久化               |
+| P0-04 | ✅   | Demo/Connected 双模式 | 认证和中性 Feature 共用运行模式，Repository 双 Adapter 已通过契约测试 |
+| P0-05 | ✅   | Feature 模块边界      | 一级公共入口、跨 Feature 深层导入和应用层反向依赖均有自动化门禁       |
+
+### 2. 身份、会话与访问控制
+
+| 编号  | 状态 | 能力                 | 完成标准                                                           |
+| ----- | ---- | -------------------- | ------------------------------------------------------------------ |
+| P0-06 | ✅   | 登录、退出和回跳     | 支持认证、退出、未登录拦截、登录后安全回跳及开放重定向防护         |
+| P0-07 | ✅   | 会话刷新与失效       | 并发刷新去重、401 清理、请求重放边界和会话存储策略有测试           |
+| P0-08 | ✅   | 路由与菜单权限       | 路由进入、侧边栏和命令搜索从同一权限元数据派生                     |
+| P0-09 | ✅   | 操作级权限组件       | `usePermission`、`Can` 与表格现有 `hidden/disabled` 共用认证权限源 |
+| P0-10 | ✅   | 请求级权限约束       | Query/Mutation 可在生成客户端调用前阻断；后端仍是最终授权边界      |
+| P0-11 | ✅   | 权限变更后的状态刷新 | 授权快照变化后统一刷新会话版本、查询缓存、当前路由与可见操作       |
+
+### 3. API、服务端数据与契约
+
+| 编号  | 状态 | 能力                    | 完成标准                                                                    |
+| ----- | ---- | ----------------------- | --------------------------------------------------------------------------- |
+| P0-12 | ✅   | OpenAPI 客户端生成      | 通过 `swagger-typescript-api` 按服务生成、临时目录校验并原子替换            |
+| P0-13 | ✅   | 生成代码所有权          | 生成目录禁止手改，业务请求只能通过生成客户端和统一请求生命周期              |
+| P0-14 | ✅   | 统一请求生命周期        | 认证、刷新、取消、请求 ID、标准错误和用户提示通过同一组 Hook 管理           |
+| P0-15 | ✅   | 标准 `ApiError`         | 统一 `status/code/message/requestId/details/retriable`，屏蔽 Axios 响应差异 |
+| P0-16 | ✅   | 请求关联 ID             | 生成或透传 Correlation ID，响应错误可展示并供日志检索                       |
+| P0-17 | ✅   | TanStack Query 数据缓存 | 服务端数据使用 Query 管理，具备统一 QueryClient 和取消能力                  |
+| P0-18 | ✅   | Query Key 与失效约定    | 明确用户、租户、语言作用域及 Mutation 后的失效、回滚和并发策略              |
+| P0-19 | ✅   | 首个 Feature 数据模板   | 工具层维护 DTO 映射、双 Adapter、查询与 Mutation，不进入运行时 Feature      |
+
+### 4. 全局元数据
+
+| 编号  | 状态 | 能力             | 完成标准                                                                      |
+| ----- | ---- | ---------------- | ----------------------------------------------------------------------------- |
+| P0-20 | ✅   | 全局枚举系统     | 完整目录、按 Key/Value/Label 获取、作用域缓存、校验、失效和展示组件已通过验证 |
+| P0-21 | ✅   | 全局参数系统     | 后端参数具备类型校验、作用域缓存、刷新及 React/非 React 读取入口              |
+| P0-22 | ✅   | 元数据初始化编排 | 登录、认证租户/权限/语言变化后独立加载；失败可定向重试且不阻塞应用子树        |
+
+### 5. 通用交互组件
+
+| 编号  | 状态 | 能力               | 完成标准                                                            |
+| ----- | ---- | ------------------ | ------------------------------------------------------------------- |
+| P0-23 | ✅   | 全局 UI primitives | shadcn primitives 只保留一份全局源码，业务组件直接复用              |
+| P0-24 | ✅   | 标准数据表格       | `AppDataTable` 覆盖常规列表、排序、选择、分页、加载和空态           |
+| P0-25 | 🔌   | 高级表格           | `advancedTable` 按需复制；启用后校验公共入口、许可证与懒加载        |
+| P0-26 | ✅   | 配置式 PageForm    | 校验、远程选项、自定义/文件字段及未保存保护已形成公共契约与行为测试 |
+| P0-27 | ✅   | Dialog 与路由弹窗  | 普通弹窗、确认弹窗和路由弹窗具备公共入口及焦点行为测试              |
+| P0-28 | ✅   | 统一反馈状态       | 首次加载、成功空态、页面错误和 Toast 归属形成统一组件与接入契约     |
+| P0-29 | ✅   | 未保存内容保护     | PageForm/AppTable 暴露 dirty 状态，并统一拦截路由离开和关闭标签页   |
+| P0-30 | ✅   | 无障碍基线         | 浅色/深色及认证后壳层有 axe 冒烟，登录和表单错误焦点有键盘回归测试  |
+
+### 6. 配置、构建与部署
+
+| 编号  | 状态 | 能力               | 完成标准                                                              |
+| ----- | ---- | ------------------ | --------------------------------------------------------------------- |
+| P0-31 | ✅   | 构建时配置校验     | Vite 变量按运行环境校验，并输出稳定错误码、字段和可执行修复动作       |
+| P0-32 | ✅   | 运行时配置         | 同一产物可部署多环境，启动时校验 API、认证和品牌等公开配置            |
+| P0-33 | ✅   | 容器与静态站点部署 | 多阶段镜像、SPA 回退、健康检查、安全响应头和 HTTPS 主机配置已存在     |
+| P0-34 | ✅   | GitLab CI 质量门禁 | 分支和 MR 自动执行 `pnpm verify`，主分支部署依赖验证成功              |
+| P0-35 | ✅   | 构建产物晋级       | 单次构建经文件摘要、Commit 与镜像 Digest 校验后晋级，部署不再重新构建 |
+| P0-36 | ✅   | 版本与发布信息     | 页面和错误上下文可获取版本、Commit、构建时间和部署环境，但不暴露密钥  |
+
+### 7. 线上诊断与安全
+
+| 编号  | 状态 | 能力           | 完成标准                                                        |
+| ----- | ---- | -------------- | --------------------------------------------------------------- |
+| P0-37 | ✅   | 可观测性适配器 | 可插拔接入 Sentry/OpenTelemetry，覆盖全局、路由和 API 错误      |
+| P0-38 | ✅   | 隐私与日志脱敏 | Token、Cookie、个人信息和请求体采用默认拒绝的采集策略           |
+| P0-39 | ✅   | Web Vitals     | 采集 CLS、INP、LCP，包含版本和环境维度，并可独立完全关闭        |
+| P0-40 | ✅   | 浏览器安全基线 | CSP、安全响应头、依赖审计、变更契约测试和安全接入文档已进入门禁 |
+| P0-41 | ✅   | 错误恢复体验   | 页面错误保留请求 ID，按错误类型手动重试并明确旧数据与降级边界   |
+
+### 8. 工程质量与开发体验
+
+| 编号  | 状态 | 能力               | 完成标准                                                                         |
+| ----- | ---- | ------------------ | -------------------------------------------------------------------------------- |
+| P0-42 | ✅   | 本地质量命令       | ESLint、Prettier、Stylelint、Knip、Vitest Browser 和生产构建统一到 `pnpm verify` |
+| P0-43 | ✅   | 测试分层           | 单元、集成、Feature 契约、axe 与键盘登录/退出核心旅程均进入统一门禁              |
+| P0-44 | ✅   | 提交规范           | Husky、lint-staged、Commitlint 和 Conventional Commits 已配置                    |
+| P0-45 | ✅   | 组件源码治理       | 单一清单、来源差异、回归证据和第三方许可证检查已进入 verify 门禁                 |
+| P0-46 | ✅   | 脚手架初始化指南   | 只读检查命令覆盖工具链、双 Mode、Runtime Config、OpenAPI 与占位项并支持严格模式  |
+| P0-47 | ✅   | 架构边界自动检查   | Feature 内部导入、绕过生成客户端和公共入口违规均由 ESLint/测试门禁               |
+| P0-48 | ✅   | 生产候选浏览器冒烟 | 真实 Chromium 校验部署配置、React 启动和登录路由后才允许切换正式容器             |
+| P0-49 | ✅   | 脚手架初始化命令   | 严格清单支持字段预览、显式写入、失败回滚和幂等重复执行                           |
+| P0-50 | ✅   | 全局构建体积预算   | 默认入口和关键路由设定压缩后预算，超限时报告主要 Chunk 归属                      |
+| P0-51 | ✅   | 模板版本策略       | 应用/模板独立版本、变更记录、人工评审和完整 Git 回滚；第二版前不建升级引擎       |
+
+## P1：高频企业业务基础能力
+
+P1 不包含产品页面，但应该提供稳定的通用契约和组件。
+
+| 编号  | 状态 | 能力                | 完成标准                                                            |
+| ----- | ---- | ------------------- | ------------------------------------------------------------------- |
+| P1-01 | ✅   | 文件上传            | 单/多文件、进度、取消、重试、大小/MIME 校验及服务端错误处理         |
+| P1-02 | ✅   | 文件下载            | 文件名解析、Blob 错误、取消、权限和大文件策略统一                   |
+| P1-03 | ✅   | 文件预览适配        | 图片/PDF 内建，Office 等外部预览通过可替换 Adapter 接入             |
+| P1-04 | ✅   | 导入/导出任务       | 同步下载与异步任务统一反馈，不把具体导入模板写进基础组件            |
+| P1-05 | ✅   | Locale Provider     | 统一语言、时区、日期、数字、百分比和货币格式化                      |
+| P1-06 | ✅   | 国际化文案入口      | Feature 语言包、共享壳层及 Dialog/PageForm/Table 默认文案已统一接入 |
+| P1-07 | 🔌   | 租户/工作空间上下文 | `tenantWorkspace` 按需复制；默认 core 不强制全局工作空间 Provider   |
+| P1-08 | 🔌   | 通知与任务状态接口  | `activityStatus` 按需复制，不让实时生命周期进入默认应用组合         |
+| P1-09 | ✅   | 防重复提交          | Mutation 幂等键、按钮状态、超时恢复和结果确认有统一策略             |
+| P1-10 | ✅   | 表格批量操作入口    | Table 统一选择与回调；Feature 组合权限、确认、批量接口和结果反馈    |
+| P1-11 | ✅   | 表格筛选与偏好      | Table 统一查询、排序、分页、字段顺序与隐藏偏好，不重复建立状态层    |
+| P1-12 | ✅   | 数据脱敏展示        | 手机号、证件号等展示与复制规则可配置，不能替代后端数据权限          |
+| P1-13 | ✅   | Feature 生成器      | 从中性模板生成模块骨架，支持预览、冲突保护且不自动注册产品路由      |
+
+## P2：项目按需适配
+
+P2 只定义接入边界、依赖预算和退出策略；没有实际项目需求时不增加依赖。
+
+| 编号  | 状态 | 能力                             | 默认交付策略                                            |
+| ----- | ---- | -------------------------------- | ------------------------------------------------------- |
+| P2-01 | 🔌   | SSO/OIDC、MFA、Step-up           | `advancedAuthentication` 按需复制，不进入默认 core      |
+| P2-02 | 🔌   | Feature Flag、灰度和 Kill Switch | `featureFlags` 按需复制，关键回退路径不依赖远端服务在线 |
+| P2-03 | 🔌   | 审计日志                         | `auditLogs` 能力按需复制；审计事实和权限由后端负责      |
+| P2-04 | 🔌   | 实时协作                         | `realtimeCollaboration` 按需复制并隔离 SDK 生命周期     |
+| P2-05 | 🔌   | 报表、打印和模板                 | `reporting` 能力按需复制，不进入 core 项目              |
+| P2-06 | 🔌   | 地图、富文本和图形编辑器         | `optionalEditors` 提供接入源码，具体 SDK 由项目选择     |
+| P2-07 | ⏸    | 微前端                           | 只有独立团队、发布和运行时隔离成立时才重新评估          |
+| P2-08 | ⏸    | 离线能力                         | 当前不注册 Service Worker；有明确离线业务后再重新评估   |
+| P2-09 | ✅   | 多品牌/白标                      | 建立运行时主题和资产契约，不复制应用源码                |
+| P2-10 | ⏸    | 移动端增强                       | 不承诺移动端查看或操作；只保留桌面窄窗口基本布局        |
+
+## 明确不进入脚手架核心
+
+- 用户、角色、组织、菜单管理等系统管理页面。
+- 客户、供应商、商品、区域和行业等业务主数据。
+- 审批流设计器、表单设计器和低代码运行时。
+- 万能 CRUD 工厂、万能事件总线或镜像服务端数据的全局 Store。
+- OSS、S3、监控、即时通信等供应商的硬编码实现。
+- 任何试图用前端权限替代后端授权的实现。
+- 只为展示能力而进入默认路由、默认菜单或首屏包的示例页面。
+
+## 当前落地顺序
+
+每次只推进一个编号；完成后同步更新实现、测试、接入文档和本台账状态。
+
+已完成：`P0-34` GitLab Merge Request/分支质量门禁、`P0-32` 运行时配置与启动校验、
+`P0-15` 标准 `ApiError`、`P0-16` 请求关联 ID、`P0-36` 版本与发布信息、
+`P0-37` 可观测性 Adapter、`P0-38` 隐私与日志脱敏、`P0-18` Query 约定、
+`P0-19` Feature 数据模板、`P0-05` Feature 模块边界、`P0-47` 架构边界自动检查、
+`P0-48` 生产候选浏览器冒烟、`P0-49` 脚手架初始化命令、`P0-50` 全局构建体积预算、
+`P0-30` 无障碍基线、`P0-43` 测试分层、`P0-28` 统一反馈状态、
+`P0-41` 错误恢复体验、`P0-31` 构建时配置校验、`P0-46` 脚手架初始化指南、
+`P0-35` 构建产物晋级、`P0-39` Web Vitals、`P0-40` 浏览器安全基线、
+`P0-25` 高级表格按需能力、`P0-26` 配置式 PageForm、`P0-45` 组件源码治理、
+`P1-09` 防重复提交、`P1-10` 表格批量操作入口、`P1-11` 表格筛选与偏好、
+`P1-12` 数据脱敏展示、
+`P1-13` Feature 生成器、`P0-51` 模板版本与升级策略。
+
+已完成核心边界：`P2-09` 部署级多品牌运行时主题和资产契约。
+
+按需能力源：`P1-07` 租户/工作空间、`P1-08` 通知与任务状态、`P2-01` 高级认证编排、`P2-02` Feature Flag、
+`P2-03` 审计日志、`P2-04` 实时协作、`P2-05` 报表打印和 `P2-06` 可选编辑器均由完整模板
+仓库维护，但不会进入默认 core 项目。
+
+暂缓：
+
+- `P2-07` 微前端。当前脚手架仍是单体前端，没有独立团队、独立发布节奏或必须隔离的
+  运行时；条件未成立前不增加 Module Federation、路由编排或跨应用通信基础设施。
+- `P2-08` 离线能力。当前没有断网继续操作的业务要求，不注册 Service Worker、不持久化
+  React Query 服务端数据，也不建立离线写入或冲突队列；出现明确离线场景后再评估缓存、
+  权限过期和敏感数据清理策略。
+- `P2-10` 移动端增强。脚手架定位为桌面管理后台，不把手机查看、审批或基础操作作为验收
+  范围；现有侧边栏折叠和窄窗口布局继续服务桌面窗口缩放，不新增移动专用页面或交互。
+
+后续新增能力继续遵循后端契约、Feature Adapter 和共享组件三层边界，并先确认真实业务
+场景后再进入本清单。
+
+## 单项交付模板
+
+每个编号开始前先记录以下内容：
+
+```text
+目标编号：
+用户/开发者场景：
+现有实现与缺口：
+公共契约与主要消费者：
+不在本次范围：
+失败、取消、并发与权限策略：
+验收测试：
+文档与迁移影响：
+```
+
+完成定义：代码、导出类型、测试和接入文档全部落地，`pnpm verify` 通过，并且最终
+Diff 不混入其他编号的顺手重构。