71 lines
4.5 KiB
Markdown
71 lines
4.5 KiB
Markdown
# 模块样式隔离与按需加载 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 校验说明
|