- 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>
5.6 KiB
模组完全独立互不影响 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/sessionStoragekey 不带模组前缀等违规模式,非零退出;接入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、第三方注入禁令等规则,以及双门禁运行方式