feat: 模组全维度独立,消除全局 DOM/Portal/存储污染

- jieya-ibp/welltrust-qap ThemeContext 改为作用域容器承载 CSS 变量与背景色,不再写 document
- 删除 order-cost CostCockpit 对 documentElement 的死变量写入
- bomx Drawer createPortal 挂载点内移到 .bomx-app,移除 document.body 兜底
- knowledge-graph 拖拽 cursor 改为根容器 ref
- 新增 check-module-independence 门禁并接入 build
- SOP 与融合技能文档补充「模组完全独立互不影响」章节

Co-Authored-By: Claude Sonnet 4.6 noreply@anthropic.com>
This commit is contained in:
dongsk
2026-10-19 09:10:30 +08:00
co-authored by Claude Sonnet 4.6 noreply@anthropic.com>
parent 9c45aedbe8
commit 8699798ea5
14 changed files with 683 additions and 74 deletions
@@ -5,12 +5,13 @@
---
## 0. 核心原则(先记住这四条)
## 0. 核心原则(先记住这五条)
1. **样式绝对隔离**:模块 CSS 随 React.lazy 路由 chunk 按需加载(进入模块才下载该模块 JS+CSS),但加载后仍全局生效,任何裸元素选择器、`:root`/`body` 全局规则、裸 class/ID 选择器都会跨模块污染。**模块所有 CSS 选择器必须挂在模块根容器类下**;同名 `@keyframes` 与同名工具类若值不同,必须重命名或作用域化。
2. **路由与资源目录永不同名**:模块路由名(如 `/wuc-quotation`)绝不能与 `dist` 下静态资源目录同名,否则 nginx `try_files $uri` 命中目录触发自动 301 补斜杠重定向,Location 会带上容器内端口(8901)泄漏进浏览器地址栏,随后 403(详见 §3、§8)。资源统一放 `public/mod-assets/<模块名>/`。
2. **路由与资源目录永不同名**:模块路由名(如 `/wuc-quotation`)绝不能与 `dist` 下静态资源目录同名,否则 nginx `try_files $uri` 命中目录触发自动 301 补斜杠重定向,Location 会带上容器内端口(8901)泄漏进浏览器地址栏,随后 403(详见 §3、§9)。资源统一放 `public/mod-assets/<模块名>/`。
3. **零平台侵入**:模块不得修改 `document.body`/`document.documentElement` 的 class/style,不得占用全局 localStorage key,不得与平台路由冲突。
4. **入口职责迁移**:源项目 `main.tsx` 中的 Provider 包裹、全局 CSS 引入等职责,全部迁移到模块 `App.tsx`,平台路由直接渲染模块默认导出。
5. **全维度独立**:模块必须做到「挂载即用、卸载即净」——CSS 变量与主题令牌挂模块根容器或 ThemeProvider 作用域 div,靠继承生效、卸载即消失;禁止写 `document.documentElement`/`document.body` 的 style/classList,禁止向 `document.head` 注入 link/style/script;localStorage/sessionStorage key 必须带模块前缀(平台 `userToken`/`userInfo` 白名单除外);Portal 挂载点必须在模块根容器内部;`document.title` 由平台 `ModuleTitle` 托管;事件监听与定时器必须在 `useEffect` 返回中卸载清理。由 `check:independence` 门禁零容忍拦截(见 §5.9)。
---
@@ -29,7 +30,7 @@
| 内嵌资产 | grep `data:` | base64 data URI 无需处理 |
| 存储 key | grep `localStorage`/`sessionStorage` | key 必须带项目前缀,无前缀需加 |
| keyframes | grep `@keyframes` | 与全平台 CSS 比对命名唯一性 |
| React 版本 | `package.json` | 平台为 React 18.3 + @types/react 19,注意类型差异(见 §5.3) |
| React 版本 | `package.json` | 平台为 React 18.3 + @types/react 19,注意类型差异(见 §6.3) |
---
@@ -125,7 +126,7 @@ return <div className="xxx-root" ref={rootRef}>...</div>
### 4.5 全局选择器门禁(check:styles)
`scripts/check-module-styles.mjs`(`npm run check:styles`)是样式隔离的零容忍门禁:以状态机逐字符解析扫描 `src/modules/**/*.css`(兼容数 MB 的 minified CSS 与 data URI 字符串),命中裸标签选择器(`button`/`table` 等)、裸 `:root`/伪类伪元素(`::-webkit-scrollbar` 等)、通配符 `*`、裸属性选择器、`@import` 引入 reset/normalize 即判违规,非零码退出。已接入 build 门禁(`npm run build` = `tsc -b && npm run check:styles && vite build`),日常可单独运行:
`scripts/check-module-styles.mjs`(`npm run check:styles`)是样式隔离的零容忍门禁:以状态机逐字符解析扫描 `src/modules/**/*.css`(兼容数 MB 的 minified CSS 与 data URI 字符串),命中裸标签选择器(`button`/`table` 等)、裸 `:root`/伪类伪元素(`::-webkit-scrollbar` 等)、通配符 `*`、裸属性选择器、`@import` 引入 reset/normalize 即判违规,非零码退出。已接入 build 门禁(`npm run build` = `tsc -b && npm run check:styles && npm run check:independence && vite build`,双门禁见 §5.9),日常可单独运行:
```bash
npm run check:styles # 退出码 0 = 模块 CSS 无全局选择器违规
@@ -133,9 +134,78 @@ npm run check:styles # 退出码 0 = 模块 CSS 无全局选择器违规
---
## 5. 代码适配
## 5. 模组完全独立互不影响(全维度隔离)
### 5.1 入口与 Provider
模块在平台中是「挂载即用、卸载即净」的独立单元,任何逃逸到全局的副作用都会污染首页与其它模块。本节是样式隔离(§4)之外的运行时隔离规则,与 `check:styles` 共同构成双门禁。
### 5.1 CSS 选择器命名空间
见 §4——所有选择器必须挂模块根容器类(`.xxx-root`),此处不重复。
### 5.2 CSS 变量与主题令牌作用域
- **禁止**向 `document.documentElement` / `document.body` 写入 CSS 变量、`style`、`classList`。
- 主题令牌(`--xxx` 变量、`background`、`color`、`font-family` 等)一律挂在**模块根容器**或模块内的 `ThemeProvider` 作用域 `div` 上,靠 CSS 继承向下生效。
- 模块卸载(路由切走)后,根容器及其子树从 DOM 移除,所有令牌随之消失,不残留到首页。
- 若源项目用 `document.documentElement.style.setProperty('--xxx', ...)` 切换主题,改为 `rootRef.current?.style.setProperty(...)` 或在根容器上切类。
### 5.3 全局 DOM 写入禁令
- **禁止**修改 `document.body` / `document.documentElement` 的 `style` 或 `classList`(如 `body.style.overflow`、`body.classList.toggle('dark')`)。
- **禁止**向 `document.head` 注入 `<link>`、`<style>`、`<script>` 标签。
- 需要锁滚动、切主题等副作用时,一律作用于模块根容器 `ref`,并在卸载时恢复。
### 5.4 存储 key 必须带模块前缀
- localStorage / sessionStorage 的 key 必须带模块前缀(如 `wuchuan-quotation-v1`、`sp_theme`、`ocDataSourceMode`、`welltrust-qap-*` 等)。
- **白名单**:平台级 `userToken`、`userInfo` 可直接读写,模块不得新增其它无前缀全局 key。
- 切换主题等本地偏好也用前缀 key,不得复用无命名空间的 `theme` / `darkMode`。
### 5.5 事件监听与定时器必须卸载清理
- 所有 `addEventListener`(`window` / `document` / `rootRef`)、`setTimeout`、`setInterval`、`requestAnimationFrame` 必须在 `useEffect` 的返回函数中 `removeEventListener` / `clearTimeout` / `clearInterval` / `cancelAnimationFrame`。
- 模块可被用户随时切走,残留监听器会跨模块执行并导致内存泄漏。
### 5.6 Portal 挂载点必须在模块根容器内部
- 弹窗、抽屉、Tooltip 等 `ReactDOM.createPortal(...)` 的第二个参数(容器)**必须**指向模块根容器内部的节点(如 `rootRef.current` 或根容器内的 `<div id="xxx-portal-root">`)。
- **禁止**挂到 `document.body`——否则模块卸载后 Portal DOM 残留在 body,样式与交互污染全局。
- 若第三方组件默认 portal 到 body,需通过 API 指定 `getContainer` / `appendTo` / `container` 为模块根容器。
### 5.7 document.title 由平台托管
- 模块**不得**自行 `document.title = ...`。
- 平台 `ModuleTitle` 组件在进入模块时设置标题为模块中文名,卸载时恢复 `'EIOSpace'`(见 §7 平台注册)。
### 5.8 第三方全局样式/脚本注入禁令
- 禁止在模块代码中动态 `<script src="...">` 注入第三方 SDK 到 `document.head` / `document.body`(如统计、地图、编辑器);必须用时改为 `import` 打包或挂到模块根容器内。
- 禁止 `@import` 全局 reset / normalize(见 §4.4)。
### 5.9 双门禁(check:styles + check:independence)
| 门禁 | 命令 | 零容忍范围 |
|---|---|---|
| 样式门禁 | `npm run check:styles` | CSS 全局选择器(裸标签、`:root`、`*`、`@import` reset 等,见 §4.5) |
| 独立门禁 | `npm run check:independence` | 全局 DOM 写入(`document.body` / `documentElement` 的 style/classList)、`document.head` 注入 link/style/script、`document.body` Portal、无前缀 storage key |
双门禁已接入 build:
```bash
npm run build # = tsc -b && npm run check:styles && npm run check:independence && vite build
```
日常可单独运行:
```bash
npm run check:independence # 退出码 0 = 无全局 DOM / Portal / 无前缀 storage 违规
```
---
## 6. 代码适配
### 6.1 入口与 Provider
```tsx
// App.tsx 末尾:平台路由直接渲染默认导出,Provider 职责从 main.tsx 移到这里
@@ -152,13 +222,13 @@ export default function App() {
同时把源 `main.tsx` 的 CSS import 全部搬到模块 `App.tsx` 顶部(保持原有顺序)。
### 5.2 严格 tsconfig 适配(tsc -b 报错清单)
### 6.2 严格 tsconfig 适配(tsc -b 报错清单)
- `TS6133` 未使用变量/import → 删除(含解构中未使用的成员)
- `TS2554`:`useRef<T>()` → `useRef<T | undefined>(undefined)`(@types/react 19 要求初始值)
- 默认导入 `import React` 未使用 → 删除(react-jsx transform 无需)
### 5.3 其他常见点
### 6.3 其他常见点
- 事件监听/定时器在组件卸载时清理(模块可被随时切走)
- 弹窗内 `dangerouslySetInnerHTML` 注入的 HTML,其类名也要被命名空间 CSS 覆盖(确认前缀后仍能匹配)
@@ -166,7 +236,7 @@ export default function App() {
---
## 6. 平台注册(三件套 + 图标)
## 7. 平台注册(三件套 + 图标)
```ts
// 1. src/modules/<name>/index.ts
@@ -205,12 +275,13 @@ const XxxApp = lazy(() => import('@/modules/<name>/App'));
---
## 7. 验证清单
## 8. 验证清单
**构建层**
- [ ] `npx tsc --noEmit` 通过
- [ ] `npm run build` 通过(注意 `tsc -b` 比 `tsc --noEmit` 更严,以 build 为准;已含 `check:styles` 门禁)
- [ ] `npm run build` 通过(注意 `tsc -b` 比 `tsc --noEmit` 更严,以 build 为准;已含 `check:styles` + `check:independence` 双门禁)
- [ ] `npm run check:styles` 退出码 0(模块 CSS 全局选择器零容忍门禁,见 §4.5,已接入 build)
- [ ] `npm run check:independence` 退出码 0(全局 DOM 写入 / body Portal / 无前缀 storage key 零容忍门禁,见 §5.9,已接入 build)
- [ ] `dist/mod-assets/<name>/` 资源齐全
- [ ] **`ls dist/` 确认根目录下没有与模块路由同名的目录**(防端口泄漏,见 §3)
@@ -226,6 +297,8 @@ sessionStorage.setItem('userInfo', JSON.stringify({ name: '演示用户', userId
- [ ] 首页出现新模块卡片(图标、配色正确)
- [ ] 首页(未进入任何模块)Network 面板无任何模块级 CSS chunk
- [ ] 首次进入模块路由时按需加载对应 JS+CSS chunk(React.lazy 生效)
- [ ] **进入模块再返回首页,首页视觉无污染**(body class/style 无残留、CSS 变量无残留、无 Portal 残留 DOM)
- [ ] **弹窗/抽屉等 Portal 的 DOM 位于模块根容器内部**(Elements 面板检查,非 `document.body` 直接子节点)
**回归层(改了旧模块 CSS 时必做)**
- [ ] 新模块关键布局 computed style 复核(如 nav 的 display)
@@ -234,7 +307,7 @@ sessionStorage.setItem('userInfo', JSON.stringify({ name: '演示用户', userId
---
## 8. 部署注意(nginx)
## 9. 部署注意(nginx)
- `nginx.conf` SPA 回退必须是 `try_files $uri /index.html;`——**禁止 `$uri/`**(目录命中 → 403 且不回退)
- **必须加两条重定向加固**(防止容器内端口泄漏到浏览器地址栏,2026-10 事故根因):
@@ -260,7 +333,7 @@ curl -sI https://ai-workshop.digiwincloud.com.cn/<name> | head -5
---
## 9. 历史踩坑速查表
## 10. 历史踩坑速查表
| 案例 | 坑 | 修复 |
|---|---|---|