diff --git a/.trae/specs/isolate-and-lazyload-module-styles/checklist.md b/.trae/specs/isolate-and-lazyload-module-styles/checklist.md new file mode 100644 index 0000000..775dc3e --- /dev/null +++ b/.trae/specs/isolate-and-lazyload-module-styles/checklist.md @@ -0,0 +1,12 @@ +# Checklist +- [ ] `src/App.tsx` 全部模块组件改为 `React.lazy()` 动态导入,`` 兜底生效 +- [ ] `npx tsc -b` 类型检查通过 +- [ ] `npm run build` 成功,`dist/assets` 中每个模块的 CSS 为独立 chunk 文件 +- [ ] `scripts/check-module-styles.mjs` 存在且能正确检测 `:root`/`html`/`body`/`*`/裸元素选择器/`@import` 重置,违规时非 0 退出并列出文件+行号 +- [ ] `package.json` 含 `check:styles` 脚本,且 `build` 脚本已接入该门禁 +- [ ] `bomx-reuse-analyzer/styles.css` 无 `:root` 残留,模块页面 CSS 变量取值正常、视觉无回归 +- [ ] `npm run check:styles` 退出码 0 +- [ ] 首页加载时 Network 面板无任何模块级 CSS chunk +- [ ] 跳转 `supplier-platform`/`wuc-quotation`/`bomx-reuse-analyzer` 时按需加载对应样式且渲染正常、无控制台报错 +- [ ] 平台首页与登录页视觉未受模块样式污染 +- [ ] `docs/react-module-integration-sop.md` 与 `.trae/skills/react-module-integration/SKILL.md` 已包含 lazy 路由约定与 check:styles 校验说明 diff --git a/.trae/specs/isolate-and-lazyload-module-styles/spec.md b/.trae/specs/isolate-and-lazyload-module-styles/spec.md new file mode 100644 index 0000000..faea25b --- /dev/null +++ b/.trae/specs/isolate-and-lazyload-module-styles/spec.md @@ -0,0 +1,70 @@ +# 模块样式隔离与按需加载 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 校验说明 diff --git a/.trae/specs/isolate-and-lazyload-module-styles/tasks.md b/.trae/specs/isolate-and-lazyload-module-styles/tasks.md new file mode 100644 index 0000000..31a6a59 --- /dev/null +++ b/.trae/specs/isolate-and-lazyload-module-styles/tasks.md @@ -0,0 +1,25 @@ +# Tasks +- [ ] Task 1: 路由级懒加载改造 + - [ ] SubTask 1.1: `src/App.tsx` 将 12 个模块组件的静态 import 全部改为 `React.lazy(() => import('...'))` + - [ ] SubTask 1.2: `` 外层包 ``,提供平台风格 loading 兜底(居中 spinner + "模块加载中"文案) + - [ ] SubTask 1.3: 验证 `npx tsc -b` 类型检查通过;`npm run build` 后确认 `dist/assets` 中各模块 CSS 拆分为独立文件 +- [ ] Task 2: 样式隔离自动检查脚本 + - [ ] SubTask 2.1: 新增 `scripts/check-module-styles.mjs`:递归扫描 `src/modules/**/*.css`,检测 `:root`/`html`/`body`/`*` 选择器、裸元素选择器(无类/ID/命名空间前缀的元素标签规则)、`@import` 全局重置;违规输出文件+行号+选择器,非 0 退出 + - [ ] SubTask 2.2: `package.json` 注册 `"check:styles": "node scripts/check-module-styles.mjs"` +- [ ] Task 3: 修复存量违规 + - [ ] SubTask 3.1: `src/modules/bomx-reuse-analyzer/styles.css` 的 `:root { --xxx }` 变量迁移至模块根容器类;核对 `BomxReuseHome.tsx` 根容器类名并确认页面变量取值正常 + - [ ] SubTask 3.2: `npm run check:styles` 退出码 0(存量违规清零) +- [ ] Task 4: 构建门禁与文档同步 + - [ ] SubTask 4.1: `package.json` 的 `build` 脚本接入 `check:styles`(`tsc -b && npm run check:styles && vite build`) + - [ ] SubTask 4.2: 更新 `docs/react-module-integration-sop.md`:新增「路由必须 lazy 动态导入」约定与 check:styles 校验说明 + - [ ] SubTask 4.3: 同步 `.trae/skills/react-module-integration/SKILL.md`(红线与验证清单补充懒加载要求) +- [ ] Task 5: 端到端验证 + - [ ] SubTask 5.1: `npm run dev` 启动,浏览器验证:首页 Network 无任何模块 CSS chunk + - [ ] SubTask 5.2: 依次跳转 `supplier-platform`、`wuc-quotation`、`bomx-reuse-analyzer`:按需加载对应 chunk、界面渲染正常、无控制台报错 + - [ ] SubTask 5.3: 抽查首页与登录页视觉无污染、`bomx-reuse-analyzer` 页面样式无回归 + +# Task Dependencies +- Task 3 依赖 Task 2(需要脚本先检测出违规) +- Task 4 依赖 Task 2、Task 3(违规清零后才接入构建门禁) +- Task 5 依赖 Task 1(懒加载完成后方可验证按需加载);SubTask 5.3 依赖 Task 3 +- Task 2 与 Task 1 无依赖,可并行