Files
dongskandClaude Sonnet 4.6 noreply@anthropic.com> 8699798ea5 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>
2026-10-19 09:10:30 +08:00

5.6 KiB
Raw Permalink Blame History

模组完全独立互不影响 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 注入 <link>/<style>/<script>;模组的 CSS 变量、背景色、文字色等主题令牌 SHALL 仅作用于模组根容器及其后代。

Scenario: 访问 jieya-ibp 后回到首页

  • WHEN 用户进入 /jieya-ibp 再返回首页 /
  • THEN 首页背景色与文字色为平台默认值,未被 jieya 的深色主题覆盖

Scenario: 主题令牌仅在模组内生效

  • WHEN jieya-ibp 切换明暗主题
  • THEN --body-bg/--scroll-thumb/--glow-color/--hover-bg 等变量仅在 .jieya-root 子树内生效,getComputedStyle(document.documentElement).getPropertyValue('--body-bg') 不含模组值

Requirement: 模组门户(Portal)挂载于模组根容器内

系统 SHALL 保证模组的弹窗/抽屉等 Portal 内容挂载在模组根容器内部的 DOM 节点,而非 document.body,避免全局 body 出现非模组受控的 DOM。

Scenario: bomx 抽屉挂载点

  • WHEN 打开 bomx-reuse-analyzer 的 Drawer
  • THEN 抽屉 DOM 节点位于 .bomx-app 子树内,而非 document.body 的直接子节点

Requirement: 模组独立自动化门禁

系统 SHALL 提供 npm run check:independence 脚本,扫描模组代码中的全局 DOM 写入、head 注入、body Portal、无前缀 storage key 等独立违规,作为构建门禁。

Scenario: 门禁通过

  • WHEN 所有模组均无全局 DOM 写入、Portal 均挂在根容器内、storage key 均带模组前缀
  • THEN npm run check:independence 退出码 0

Scenario: 门禁发现违规

  • WHEN 某模组存在 document.body.style.xxx 或 createPortal(x, document.body)
  • THEN 脚本输出违规文件+行号+原因,退出码非 0,npm run build 失败

Requirement: 模组独立规则文档化

SOP 文档与 react-module-integration 技能 SHALL 包含「模组完全独立互不影响」的完整规则清单与双门禁(check:styles + check:independence)说明。

Scenario: 查阅文档

  • WHEN 查阅 SOP 或技能文件
  • THEN 可找到全局 DOM 写入禁令、CSS 变量作用域、storage key 前缀、事件/定时器清理、Portal 挂载、document.title、第三方注入禁令等规则,以及双门禁运行方式