Files
2026-10-18 21:50:40 +08:00

4.5 KiB
Raw Permalink Blame History

模块样式隔离与按需加载 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 的 :root CSS 变量迁移到模块根容器类下。
  • 构建管线接入:存量违规清零后,将 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 校验说明