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:
co-authored by
Claude Sonnet 4.6 noreply@anthropic.com>
parent
9c45aedbe8
commit
8699798ea5
@@ -0,0 +1,58 @@
|
||||
# 模组完全独立互不影响 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、第三方注入禁令等规则,以及双门禁运行方式
|
||||
Reference in New Issue
Block a user