# 模组完全独立互不影响 Spec
## Why
此前已完成「模组 CSS 按需加载 + 选择器命名空间隔离」(spec `isolate-and-lazyload-module-styles`),但跨模组污染不止 CSS 一项。审计发现仍存在模组在运行时直接写入全局 DOM 且卸载不恢复的行为(jieya-ibp / welltrust-qap 的 ThemeContext 把 CSS 变量写到 `document.documentElement`、把 `background`/`color` 写到 `document.body`;order-cost-analysis 的 CostCockpit 向 `documentElement` 写 `--body-bg` 死变量)。这些值在用户离开模组后仍残留在全局,会污染首页与其它模组的视觉。从「每个模组完全独立、互不影响」的角度,需要在 CSS 之外补齐全局 DOM、存储、事件、Portal 等维度的隔离,并把规则沉淀进 SOP 与技能文档。
## What Changes
- **修复全局 DOM 写入污染**:jieya-ibp 与 welltrust-qap 的 `ThemeContext` 不再写 `document.documentElement` / `document.body`,改为由 `ThemeProvider` 渲染的作用域容器承载 CSS 变量与背景/文字色(CSS 变量向下继承,模组内所有 `var(--xxx)` 正常取值);order-cost-analysis CostCockpit 移除向 `documentElement` 写 `--body-bg` 的死代码。
- **Portal 挂载规范化**:bomx Drawer 目前用 `createPortal(..., document.body)`(已用 `.bomx-app` 包裹层解决 CSS 作用域);作为最佳实践,将 Portal 内容挂到模块根容器内的 Portal 挂载点,避免全局 body 出现非受控 DOM。
- **新增模组独立门禁脚本**:`scripts/check-module-independence.mjs`,扫描 `src/modules/**/*.{ts,tsx,js,jsx}`,检测 `document.body.style`/`document.body.classList`、`document.documentElement.style`/`setAttribute`、`document.head.appendChild`/`insertBefore`(注入 link/style)、`createPortal` 第二参数为 `document.body`、`localStorage`/`sessionStorage` key 不带模组前缀等违规模式,非零退出;接入 `npm run check:independence` 并加入 `build` 门禁。
- **文档沉淀**:更新 `docs/react-module-integration-sop.md` 与 `.trae/skills/react-module-integration`(含 references 副本),新增「模组独立不互相影响」章节,覆盖:CSS 选择器命名空间、CSS 变量作用域、全局 DOM 写入禁令、storage key 前缀、事件/定时器卸载清理、Portal 挂载、document.title、第三方全局样式/脚本注入禁令,并给出 check:styles + check:independence 双门禁说明。
## Impact
- Affected specs: `isolate-and-lazyload-module-styles`(CSS 隔离已完成,本 spec 扩展到全维度)
- Affected code:
- `src/modules/jieya-ibp/context/ThemeContext.tsx`、`src/modules/welltrust-qap/context/ThemeContext.tsx`(全局写入改作用域容器)
- `src/modules/order-cost-analysis/pages-orig/CostCockpit.tsx`(移除死变量写入)
- `src/modules/bomx-reuse-analyzer/components/Drawer.tsx`(Portal 挂载点内移)
- `scripts/check-module-independence.mjs`(新增)
- `package.json`(新增 `check:independence`,build 接入)
- `docs/react-module-integration-sop.md`、`.trae/skills/react-module-integration/SKILL.md`、`.trae/skills/react-module-integration/references/react-module-integration-sop.md`(文档沉淀)
## ADDED Requirements
### Requirement: 模组不得写入全局 DOM 且卸载后无残留
系统 SHALL 保证每个模组在运行期不修改 `document.body` / `document.documentElement` 的 `style`/`classList`,不向 `document.head` 注入 ``/`