# 模块样式隔离与按需加载 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()` 动态导入,外层包 `` 加载兜底;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 校验说明