4.5 KiB
4.5 KiB
模块样式隔离与按需加载 Spec
Why
当前 src/App.tsx 静态 import 全部 12 个模块的 App 组件,导致所有模块的 JS 与 CSS 全部打进主包,用户打开首页即下载全部模块样式(wuc-quotation 单个模块 CSS 约 7.8MB)。同时样式隔离仅依赖 SOP 中的手工命名空间约定,无自动化守护,仍存在残留全局选择器(如 bomx-reuse-analyzer/styles.css 的 :root 规则)可跨模块污染。
What Changes
- 路由级懒加载:
src/App.tsx中模块组件改为React.lazy()动态导入,外层包<Suspense>加载兜底;Vite 自动将每个模块拆为独立 JS+CSS chunk,仅在跳转到对应路由时才加载该模块样式。 - 样式隔离自动化守护:新增
scripts/check-module-styles.mjs检查脚本,扫描src/modules/**/*.css中的全局选择器(:root/html/body/*/裸元素选择器/@import全局重置),发现违规即报错退出;注册为npm run check:styles。 - 修复存量违规:
bomx-reuse-analyzer/styles.css的:rootCSS 变量迁移到模块根容器类下。 - 构建管线接入:存量违规清零后,将
check:styles纳入build脚本,防止后续模块引入全局选择器。 - 文档同步:更新 SOP 文档与 react-module-integration 技能,明确新模块接入必须使用 lazy 路由模式 + 命名空间根容器。
Impact
- Affected specs: 无既有 spec(首次建立)
- Affected code:
src/App.tsx(懒加载改造)src/modules/bomx-reuse-analyzer/styles.css(存量违规修复)scripts/check-module-styles.mjs(新增)package.json(新增 check:styles 脚本、build 接入)docs/react-module-integration-sop.md、.trae/skills/react-module-integration/SKILL.md(文档同步)
ADDED Requirements
Requirement: 模块按需加载
系统 SHALL 以 React.lazy() 动态导入方式注册全部模块路由,保证模块代码与样式拆分为独立 chunk,仅在用户导航至该模块路由时才发起加载。
Scenario: 首页不加载模块样式
- WHEN 用户登录后停留在平台首页(
/) - THEN Network 面板中不出现任何模块级 CSS chunk(如
wuc-quotation、supplier-platform的 CSS 文件)
Scenario: 跳转模块时加载对应样式
- WHEN 用户首次导航到某模块路由(如
/supplier-platform) - THEN 浏览器按需加载该模块对应的 JS 与 CSS chunk,模块界面正常渲染
Scenario: 加载期间兜底 UI
- WHEN 模块 chunk 尚在加载中
- THEN Suspense 兜底占位展示(平台风格的加载提示),加载完成后无报错切换至模块界面
Scenario: 构建产物按模块拆分
- WHEN 执行
npm run build - THEN
dist/assets中每个模块生成独立的 JS 与 CSS 产物(含路由引用关系),tsc -b类型检查通过
Requirement: 模块样式全局选择器零容忍
系统 SHALL 提供自动化检查脚本,确保 src/modules/**/*.css 中不出现全局作用选择器;检查结果 SHALL 作为构建门禁。
Scenario: 扫描通过
- WHEN 执行
npm run check:styles且所有模块 CSS 均挂在模块命名空间根容器类下 - THEN 脚本以退出码 0 结束,无违规输出
Scenario: 扫描发现违规
- WHEN 某模块 CSS 中存在
:root、html、body、*、裸元素选择器或@import全局重置 - THEN 脚本以非 0 退出码失败,并逐条输出违规文件、行号与选择器内容
Scenario: 构建门禁生效
- WHEN 模块 CSS 存在全局选择器违规时执行
npm run build - THEN 构建失败并提示先修复样式违规
Requirement: 存量违规清零
系统 SHALL 保证现有 12 个模块 CSS 无全局选择器残留,不污染平台首页、登录页及其它模块。
Scenario: bomx-reuse-analyzer 变量迁移
- WHEN
src/modules/bomx-reuse-analyzer/styles.css中存在:root { --xxx }规则 - THEN 变量定义迁移至该模块根容器类下,模块页面变量取值正常,视觉无回归
Requirement: 新模块接入约定同步
SOP 文档与 react-module-integration 技能 SHALL 同步更新:新模块路由必须使用 lazy 动态导入模式,CSS 必须挂载在模块命名空间根容器下,并通过 check:styles 校验。
Scenario: 文档含懒加载约定
- WHEN 查阅 SOP 文档或技能文件
- THEN 可找到 lazy 路由模式代码约定与 check:styles 校验说明