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,14 @@
|
||||
# Checklist
|
||||
- [x] jieya-ibp/context/ThemeContext.tsx 不再写 document.documentElement / document.body,CSS 变量与背景/文字色由 ThemeProvider 作用域容器承载
|
||||
- [x] welltrust-qap/context/ThemeContext.tsx 同上改造
|
||||
- [x] order-cost-analysis CostCockpit 移除对 documentElement 的 --body-bg 死变量写入
|
||||
- [x] bomx Drawer 的 createPortal 挂载点位于 .bomx-app 子树内,不再挂 document.body(portalMount 必传,无 document.body 兜底)
|
||||
- [x] 浏览器验证:进入 jieya 后返回首页,首页背景与文字色未被模组主题覆盖(body style 串 before==during==after)
|
||||
- [x] 浏览器验证:jieya 明暗主题切换正常(作用于 .jieya-root);welltrust 同构;bomx Drawer 当前未实例化
|
||||
- [x] scripts/check-module-independence.mjs 存在,能检出全局 DOM 写入、head 注入、body Portal、无前缀 storage key,违规非零退出
|
||||
- [x] package.json 含 check:independence,build 已接入 check:styles + check:independence 双门禁
|
||||
- [x] npm run check:independence 退出码 0
|
||||
- [x] npm run check:styles 退出码 0
|
||||
- [x] npm run build 通过
|
||||
- [x] docs/react-module-integration-sop.md 含「模组完全独立互不影响」完整规则与双门禁说明
|
||||
- [x] .trae/skills/react-module-integration/SKILL.md 与 references 副本同步更新
|
||||
@@ -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、第三方注入禁令等规则,以及双门禁运行方式
|
||||
@@ -0,0 +1,29 @@
|
||||
# Tasks
|
||||
|
||||
- [x] Task 1: 修复全局 DOM 写入污染(jieya-ibp / welltrust-qap ThemeContext)
|
||||
- [x] SubTask 1.1: `jieya-ibp/context/ThemeContext.tsx`:移除 `useEffect` 中对 `document.documentElement` 的 `setProperty` 与 `document.body.style.background/color`;改为 `ThemeProvider` 返回的 `<ThemeContext.Provider>` 内包裹一层作用域 `<div>`,以 inline style 设置 `--body-bg`/`--scroll-thumb`/`--glow-color`/`--hover-bg` 变量与 `background`/`color`(值取自 `tokens`),宽高 100% 承接 `AppInner` 的 100vw/100vh 根容器
|
||||
- [x] SubTask 1.2: `welltrust-qap/context/ThemeContext.tsx`:同 1.1 改造
|
||||
- [x] SubTask 1.3: `order-cost-analysis/pages-orig/CostCockpit.tsx`:移除向 `document.documentElement` 写 `--body-bg` 的 `useEffect`(`var(--body-bg)` 在模组内无引用,属死代码)
|
||||
- [x] SubTask 1.4: 浏览器验证:进入 jieya 再回首页,首页背景/文字色未被覆盖;jieya 明暗主题切换正常(welltrust 同构改造,tsc + build 通过)
|
||||
- [x] Task 2: Portal 挂载点内移(bomx Drawer)
|
||||
- [x] SubTask 2.1: `bomx-reuse-analyzer/pages/BomxReuseHome.tsx` 根容器内新增 Portal 挂载点 `<div ref={portalMountRef} />`
|
||||
- [x] SubTask 2.2: `bomx-reuse-analyzer/components/Drawer.tsx`:`createPortal` 第二参数改为必传 `portalMount: HTMLDivElement`,彻底移除 `document.body` 兜底
|
||||
- [x] SubTask 2.3: Drawer 当前未被任何文件引用(死代码),无运行时实例;`.bomx-app` 根容器无 transform/filter/perspective,不会破坏 fixed 遮罩
|
||||
- [x] Task 3: 新增模组独立门禁脚本
|
||||
- [x] SubTask 3.1: 新增 `scripts/check-module-independence.mjs`(ESM 零依赖),扫描 `src/modules/**/*.{ts,tsx,js,jsx}`,检测 5 类违规(body 样式写入、documentElement 写入、head 注入、body Portal、无前缀 storage key),跳过字符串与注释,违规非零退出
|
||||
- [x] SubTask 3.2: `package.json` 增加 `check:independence`;`build` 改为 `tsc -b && npm run check:styles && npm run check:independence && vite build`
|
||||
- [x] SubTask 3.3: 自测:修复后退出码 0(扫描 270 文件);故意保留/插入的违规样例可正确检出(已验证 bomx Drawer、knowledge-graph 两处真实违规被检出并修复)
|
||||
- [x] Task 4: 文档沉淀(SOP + 技能)
|
||||
- [x] SubTask 4.1: `docs/react-module-integration-sop.md` 新增 §5「模组完全独立互不影响」(5.1–5.9),覆盖全维度规则与双门禁说明;章节顺延
|
||||
- [x] SubTask 4.2: `.trae/skills/react-module-integration/SKILL.md` 红线与验证清单同步
|
||||
- [x] SubTask 4.3: `.trae/skills/react-module-integration/references/react-module-integration-sop.md` 与 docs 完全同源(diff 无输出)
|
||||
- [x] Task 5: 端到端验证
|
||||
- [x] SubTask 5.1: `npm run build` 通过(含双门禁),dist 无回归
|
||||
- [x] SubTask 5.2: 浏览器验证:首页→jieya→首页 body 样式串 before/during/after 完全一致(仅平台深色主题值),jieya 主题背景作用于 `.jieya-root`;控制台无报错
|
||||
- [x] SubTask 5.3: `npm run check:independence` 与 `npm run check:styles` 均退出码 0
|
||||
|
||||
# Task Dependencies
|
||||
- Task 1、Task 2 互相独立,可并行
|
||||
- Task 3 依赖 Task 1、Task 2(修复后门禁才能通过;门禁脚本本身可先写,用 HEAD 版本验证检出能力)
|
||||
- Task 4 与 Task 1/2/3 无代码冲突,可并行
|
||||
- Task 5 依赖 Task 1-4
|
||||
Reference in New Issue
Block a user