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
@@ -13,25 +13,28 @@ description: 将独立 React(Vite) 前端项目融合进 ai-platform 平台成
|
||||
2. **目录规划与复制**(SOP §2):源码进 `src/modules/<name>/`,禁止复制 `main.tsx`、`__tests__`。
|
||||
3. **静态资源迁移**(SOP §3):资源统一放 `public/mod-assets/<name>/`,代码引用全部改为绝对路径 `/mod-assets/<name>/xxx`(含 `locateFile`)。
|
||||
4. **样式隔离**(SOP §4):模块根容器类(如 `.xxx-root`)作为所有选择器前缀;`body`/`:root`/`html`/`#root` 规则必须改写或删除;class、ID、裸元素三类冲突源都要检测。
|
||||
5. **代码适配**(SOP §5):源 `main.tsx` 的 Provider 包裹与 CSS import 全部迁入模块 `App.tsx`;`tsc -b` 报错按清单修(TS6133、TS2554)。
|
||||
6. **平台注册**(SOP §6):`moduleConfig` + `registry.ts` + `App.tsx` 路由(模块用 `React.lazy` 动态导入 + `<Suspense fallback={<ModuleLoading />}>` 包 `<Routes>`,禁止静态 import,否则模块 CSS 进主包)+ `HomePage.tsx` ICON_MAP 四件套。
|
||||
7. **验证**(SOP §7):构建层、浏览器层(mock 登录注入)、回归层逐项打勾。
|
||||
8. **部署检查**(SOP §8):nginx 加固与生产地址冒烟。
|
||||
5. **代码适配**(SOP §6):源 `main.tsx` 的 Provider 包裹与 CSS import 全部迁入模块 `App.tsx`;`tsc -b` 报错按清单修(TS6133、TS2554)。
|
||||
6. **平台注册**(SOP §7):`moduleConfig` + `registry.ts` + `App.tsx` 路由(模块用 `React.lazy` 动态导入 + `<Suspense fallback={<ModuleLoading />}>` 包 `<Routes>`,禁止静态 import,否则模块 CSS 进主包)+ `HomePage.tsx` ICON_MAP 四件套。
|
||||
7. **验证**(SOP §8):构建层、浏览器层(mock 登录注入)、回归层逐项打勾。
|
||||
8. **部署检查**(SOP §9):nginx 加固与生产地址冒烟。
|
||||
|
||||
## 红线(违反必出事故)
|
||||
|
||||
- **路由与资源目录永不同名**:资源只放 `public/mod-assets/<name>/`,绝不能放 `public/<name>/`。否则 dist 下出现与路由同名目录,nginx 目录 301 补斜杠并把容器端口 `:8901` 泄漏进浏览器地址栏,新页签 403/空白(2026-10 生产事故,SOP §3、§8)。
|
||||
- **路由与资源目录永不同名**:资源只放 `public/mod-assets/<name>/`,绝不能放 `public/<name>/`。否则 dist 下出现与路由同名目录,nginx 目录 301 补斜杠并把容器端口 `:8901` 泄漏进浏览器地址栏,新页签 403/空白(2026-10 生产事故,SOP §3、§9)。
|
||||
- **样式绝对隔离**:所有 CSS 选择器挂模块根容器类下。模块 CSS 虽随 React.lazy 路由 chunk 按需加载,但加载后仍全局生效,裸选择器必然跨模块污染;同名 `@keyframes`/工具类若值不同必须重命名或作用域化。全局选择器由 `npm run check:styles` 零容忍门禁拦截(已接入 build,SOP §4.5);ID 选择器特异性最高,`#nav` 类冲突需给旧模块规则也加前缀(SOP §4.2)。
|
||||
- **全维度独立零容忍**:禁止写 `document.body`/`document.documentElement` 的 style/classList,禁止向 `document.head` 注入 link/style/script;Portal(弹窗/抽屉)禁止挂 `document.body`,必须挂模块根容器内;localStorage/sessionStorage key 必须带模块前缀(平台 `userToken`/`userInfo` 白名单除外);`document.title` 由平台 `ModuleTitle` 托管;事件监听/定时器必须在 useEffect 返回中清理。由 `npm run check:independence` 零容忍门禁拦截(已接入 build,SOP §5)。
|
||||
- **零平台侵入**:不改 `document.body`/`document.documentElement`,存储 key 带模块前缀,不与平台路由冲突。
|
||||
- **Provider 必须迁移**:漏迁 `AppProvider` 会导致路由渲染时 context 为 null 白屏。
|
||||
|
||||
## 验证捷径
|
||||
|
||||
- 提交/构建前跑 `npm run check:styles`(已接入 build 门禁),退出码 0 = 模块 CSS 无全局选择器违规。
|
||||
- 提交/构建前跑 `npm run check:independence`(已接入 build 门禁),退出码 0 = 无全局 DOM 写入 / body Portal / 无前缀 storage key 违规。
|
||||
- 构建后 `ls dist/` 确认根目录无与路由同名目录。
|
||||
- 部署后 `curl -sI https://生产域名/<name>` 期望 200(或 302 跳登录);出现 301 且 Location 带 `:8901` 即端口泄漏信号。
|
||||
- 浏览器验证前先注入 mock 会话:`sessionStorage.setItem('userToken', 'mock-token-for-ui-check')`。
|
||||
- 进入模块再返回首页,确认 body class/style、CSS 变量、Portal DOM 无残留(视觉无污染)。
|
||||
|
||||
## 历史踩坑速查
|
||||
|
||||
详见 SOP §9 速查表。最高频三坑:同名资源目录端口泄漏、`#nav` ID 冲突、漏迁 Provider。
|
||||
详见 SOP §10 速查表。最高频三坑:同名资源目录端口泄漏、`#nav` ID 冲突、漏迁 Provider。
|
||||
|
||||
Reference in New Issue
Block a user