Files
ai-platform/.trae/specs/isolate-and-lazyload-module-styles/spec.md
T
2026-10-18 21:50:40 +08:00

71 lines
4.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 模块样式隔离与按需加载 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 校验说明