Files
ai-platform/docs/react-module-integration-sop.md
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

350 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# React 前端项目融合 ai-platform 模块化 SOP
> 适用场景:将独立的 React 前端项目(Vite 构建)融合进 `ai-platform`,作为首页可进入的独立模块。
> 已按此 SOP 成功融合:jieya-ibp、welltrust-qap、baode-web、supplier-platform、wuc-quotation。
---
## 0. 核心原则(先记住这五条)
1. **样式绝对隔离**:模块 CSS 随 React.lazy 路由 chunk 按需加载(进入模块才下载该模块 JS+CSS),但加载后仍全局生效,任何裸元素选择器、`:root`/`body` 全局规则、裸 class/ID 选择器都会跨模块污染。**模块所有 CSS 选择器必须挂在模块根容器类下**;同名 `@keyframes` 与同名工具类若值不同,必须重命名或作用域化。
2. **路由与资源目录永不同名**:模块路由名(如 `/wuc-quotation`)绝不能与 `dist` 下静态资源目录同名,否则 nginx `try_files $uri` 命中目录触发自动 301 补斜杠重定向,Location 会带上容器内端口(8901)泄漏进浏览器地址栏,随后 403(详见 §3、§9)。资源统一放 `public/mod-assets/<模块名>/`。
3. **零平台侵入**:模块不得修改 `document.body`/`document.documentElement` 的 class/style,不得占用全局 localStorage key,不得与平台路由冲突。
4. **入口职责迁移**:源项目 `main.tsx` 中的 Provider 包裹、全局 CSS 引入等职责,全部迁移到模块 `App.tsx`,平台路由直接渲染模块默认导出。
5. **全维度独立**:模块必须做到「挂载即用、卸载即净」——CSS 变量与主题令牌挂模块根容器或 ThemeProvider 作用域 div,靠继承生效、卸载即消失;禁止写 `document.documentElement`/`document.body` 的 style/classList,禁止向 `document.head` 注入 link/style/script;localStorage/sessionStorage key 必须带模块前缀(平台 `userToken`/`userInfo` 白名单除外);Portal 挂载点必须在模块根容器内部;`document.title` 由平台 `ModuleTitle` 托管;事件监听与定时器必须在 `useEffect` 返回中卸载清理。由 `check:independence` 门禁零容忍拦截(见 §5.9)。
---
## 1. 前期勘察(融合前必做,约 10 分钟)
对源项目逐项检查并记录结论:
| 检查项 | 命令/方法 | 判定 |
|---|---|---|
| 新增依赖 | 对比 `package.json` 与 ai-platform | 原则上零新增;有新增需评估版本冲突 |
| 路由方式 | 看源 `main.tsx`/`App.tsx` | URL 子路由 → 平台路由用 `/xxx/*`;内部 state 切页 → 精确 path 即可 |
| 入口 Provider | 看 `main.tsx` 的 `<XxxProvider>` 包裹 | **必须迁移**(否则路由渲染时 context 为 null 白屏) |
| 全局 CSS | grep `html`/`body`/`:root`/`#root` | 记录所有需剥离/迁移的全局规则 |
| body 操作 | grep `document.body`、`document.documentElement` | classList.toggle/style 修改需改为模块根容器 ref |
| public 资源 | `ls public/` | 记录文件清单与代码引用位置(grep 文件名) |
| 内嵌资产 | grep `data:` | base64 data URI 无需处理 |
| 存储 key | grep `localStorage`/`sessionStorage` | key 必须带项目前缀,无前缀需加 |
| keyframes | grep `@keyframes` | 与全平台 CSS 比对命名唯一性 |
| React 版本 | `package.json` | 平台为 React 18.3 + @types/react 19,注意类型差异(见 §6.3) |
---
## 2. 目录规划与代码复制
```
ai-platform/
├── src/modules/<name>/ # 模块源码
│ ├── App.tsx # 入口(含 Provider 包裹 + CSS 引入 + 根容器)
│ ├── index.ts # moduleConfig 导出
│ ├── app/ | pages/ | ... # 源项目 src 业务代码(排除 main.tsx、__tests__)
│ └── styles/ | *.css # 源项目样式
└── public/mod-assets/<name>/ # 模块静态资源(禁止放 public/<name>/)
```
```bash
mkdir -p ai-platform/src/modules/<name> ai-platform/public/mod-assets/<name>
cp -R <源项目>/src/app ai-platform/src/modules/<name>/app
cp -R <源项目>/src/styles ai-platform/src/modules/<name>/styles
cp <源项目>/src/App.tsx ai-platform/src/modules/<name>/App.tsx
# 不要复制 main.tsx、__tests__、vite.config 等入口/测试文件
```
---
## 3. 静态资源迁移
1. `public/` 下资源全部复制到 `public/mod-assets/<name>/`;
2. grep 源码中所有相对路径引用(`src="xxx.svg"`、`href="xxx.md"`、`locateFile` 等),统一改为绝对路径 `/mod-assets/<name>/xxx`;
3. 验证:dev 下直接访问 `http://localhost:<port>/mod-assets/<name>/xxx` 返回 200;
4. build 后确认 `dist/mod-assets/<name>/` 存在。
> 为什么不用 `public/<name>/`:Vite 会把 public 目录原样拷入 dist,形成与模块路由同名的目录。完整故障链(2026-10 生产事故):
> 1. 首页卡片 `window.open('/<name>')` → nginx `try_files $uri /index.html` 的 `$uri` 命中该**目录**(非文件);
> 2. nginx 对目录请求自动 301 补斜杠(`/`),且 `port_in_redirect` 默认为 on,Location 变成 `https://域名:8901/<name>/`——**容器内端口被泄漏到浏览器地址栏**;
> 3. `:8901` 在外网不可达/无该虚拟主机 → 目录又无 index.html → 最终 403 或空白。
> 症状特征:只有"新增且带同名静态目录"的模块新页签打开异常(地址栏出现 `:8901`),老模块完全正常。
---
## 4. 样式隔离(核心,必须逐条执行)
### 4.1 根容器命名空间
模块 App 最外层包一个根容器,所有 CSS 选择器挂到它下面:
```tsx
// App.tsx
const rootRef = useRef<HTMLDivElement>(null)
return <div className="xxx-root" ref={rootRef}>...</div>
```
命名空间化有三种落地方式(按源项目 CSS 规模选择):
| 方式 | 适用 | 案例 |
|---|---|---|
| 全量脚本转换 | CSS 大/规则多(尤其 minified) | wuc-quotation:5 个 CSS 全部选择器加 `.wuc-root` 前缀 |
| 仅冲突类加前缀 | CSS 小、冲突少 | baode-web:20 处冲突选择器加 `.baode-root` |
| 原生自带命名空间 | 源项目已经做好隔离 | supplier-platform:变量与布局挂 `.hansong-app` |
**脚本转换要点**(已踩坑):
- `:root{--var}` → `.xxx-root{--var}`(CSS 变量迁到根容器)
- `body` → `.xxx-root`;`body.dark`/`body.collapsed` → `.xxx-root.dark` 等(主题/状态类改挂根容器)
- `body > #root > header` → `.xxx-root > header`(层级补偿规则改写)
- `html, body{overflow:hidden}` 等 → **直接删除**(会锁死平台整页滚动);视口锁定改由 `.xxx-root{height:100vh}` 承接
- `@media` 块内部规则**必须递归处理**(漏掉会造成窄屏规则逃逸成全局)
- `@keyframes`/`@font-face` 原样保留;字符串(data URI)不能破坏——需状态机解析而非正则替换
- 转换完必须校验:无残留 `body`/`:root`/`html`/`#root` 选择器、brace 平衡
### 4.2 三类冲突源都要检测(缺一不可)
```python
# 检测思路(对每个已存在模块 + 平台全局样式执行)
# 1. class 冲突:新模块 TSX className 集合 ∩ 双方 CSS 类名集合
# 2. ID 冲突:新模块 TSX 中的 id="xxx" ∩ 其它模块 CSS 中的 #xxx(双向)
# 3. 裸元素选择器:新模块 CSS 中 html/body/header/aside/nav/button/input 等无前缀选择器
```
> **ID 冲突是隐藏最深的坑**:`#nav` 特异性(1,0,0)碾压任何 `.wuc-root nav`(0,1,1)。wuc-quotation 上线后菜单被 supplier-platform 的 `#nav{display:flex}` 强制水平排列。修复方式是给**旧模块**的 ID 规则也加根容器前缀(`.hansong-app #nav`)。
### 4.3 运行时全局副作用清理
- `document.body.classList.toggle('dark'/'collapsed')` → `rootRef.current?.classList.toggle(...)`
- `document.body.style.overflow = ...`(如 LoginPage 的 useEffect)→ 模块内改为根容器样式或卸载时恢复
- 弹窗/Portal 挂载点若用 `document.body`,改为模块根容器内渲染
- `@media print` 中 `body{...}` 规则 → `.xxx-root{...}`,并放开视口锁定(`height:auto;overflow:visible`)
### 4.4 其它隔离项
- localStorage/sessionStorage key 带项目前缀(如 `wuchuan-quotation-v1`)
- `@keyframes` 命名全平台唯一(冲突时给新模块 keyframes 加前缀)
- 各模块 CSS 文件内不放 `@import` 全局重置(normalize/reset 一律禁止)
### 4.5 全局选择器门禁(check:styles)
`scripts/check-module-styles.mjs`(`npm run check:styles`)是样式隔离的零容忍门禁:以状态机逐字符解析扫描 `src/modules/**/*.css`(兼容数 MB 的 minified CSS 与 data URI 字符串),命中裸标签选择器(`button`/`table` 等)、裸 `:root`/伪类伪元素(`::-webkit-scrollbar` 等)、通配符 `*`、裸属性选择器、`@import` 引入 reset/normalize 即判违规,非零码退出。已接入 build 门禁(`npm run build` = `tsc -b && npm run check:styles && npm run check:independence && vite build`,双门禁见 §5.9),日常可单独运行:
```bash
npm run check:styles # 退出码 0 = 模块 CSS 无全局选择器违规
```
---
## 5. 模组完全独立互不影响(全维度隔离)
模块在平台中是「挂载即用、卸载即净」的独立单元,任何逃逸到全局的副作用都会污染首页与其它模块。本节是样式隔离(§4)之外的运行时隔离规则,与 `check:styles` 共同构成双门禁。
### 5.1 CSS 选择器命名空间
见 §4——所有选择器必须挂模块根容器类(`.xxx-root`),此处不重复。
### 5.2 CSS 变量与主题令牌作用域
- **禁止**向 `document.documentElement` / `document.body` 写入 CSS 变量、`style`、`classList`。
- 主题令牌(`--xxx` 变量、`background`、`color`、`font-family` 等)一律挂在**模块根容器**或模块内的 `ThemeProvider` 作用域 `div` 上,靠 CSS 继承向下生效。
- 模块卸载(路由切走)后,根容器及其子树从 DOM 移除,所有令牌随之消失,不残留到首页。
- 若源项目用 `document.documentElement.style.setProperty('--xxx', ...)` 切换主题,改为 `rootRef.current?.style.setProperty(...)` 或在根容器上切类。
### 5.3 全局 DOM 写入禁令
- **禁止**修改 `document.body` / `document.documentElement` 的 `style` 或 `classList`(如 `body.style.overflow`、`body.classList.toggle('dark')`)。
- **禁止**向 `document.head` 注入 `<link>`、`<style>`、`<script>` 标签。
- 需要锁滚动、切主题等副作用时,一律作用于模块根容器 `ref`,并在卸载时恢复。
### 5.4 存储 key 必须带模块前缀
- localStorage / sessionStorage 的 key 必须带模块前缀(如 `wuchuan-quotation-v1`、`sp_theme`、`ocDataSourceMode`、`welltrust-qap-*` 等)。
- **白名单**:平台级 `userToken`、`userInfo` 可直接读写,模块不得新增其它无前缀全局 key。
- 切换主题等本地偏好也用前缀 key,不得复用无命名空间的 `theme` / `darkMode`。
### 5.5 事件监听与定时器必须卸载清理
- 所有 `addEventListener`(`window` / `document` / `rootRef`)、`setTimeout`、`setInterval`、`requestAnimationFrame` 必须在 `useEffect` 的返回函数中 `removeEventListener` / `clearTimeout` / `clearInterval` / `cancelAnimationFrame`。
- 模块可被用户随时切走,残留监听器会跨模块执行并导致内存泄漏。
### 5.6 Portal 挂载点必须在模块根容器内部
- 弹窗、抽屉、Tooltip 等 `ReactDOM.createPortal(...)` 的第二个参数(容器)**必须**指向模块根容器内部的节点(如 `rootRef.current` 或根容器内的 `<div id="xxx-portal-root">`)。
- **禁止**挂到 `document.body`——否则模块卸载后 Portal DOM 残留在 body,样式与交互污染全局。
- 若第三方组件默认 portal 到 body,需通过 API 指定 `getContainer` / `appendTo` / `container` 为模块根容器。
### 5.7 document.title 由平台托管
- 模块**不得**自行 `document.title = ...`。
- 平台 `ModuleTitle` 组件在进入模块时设置标题为模块中文名,卸载时恢复 `'EIOSpace'`(见 §7 平台注册)。
### 5.8 第三方全局样式/脚本注入禁令
- 禁止在模块代码中动态 `<script src="...">` 注入第三方 SDK 到 `document.head` / `document.body`(如统计、地图、编辑器);必须用时改为 `import` 打包或挂到模块根容器内。
- 禁止 `@import` 全局 reset / normalize(见 §4.4)。
### 5.9 双门禁(check:styles + check:independence)
| 门禁 | 命令 | 零容忍范围 |
|---|---|---|
| 样式门禁 | `npm run check:styles` | CSS 全局选择器(裸标签、`:root`、`*`、`@import` reset 等,见 §4.5) |
| 独立门禁 | `npm run check:independence` | 全局 DOM 写入(`document.body` / `documentElement` 的 style/classList)、`document.head` 注入 link/style/script、`document.body` Portal、无前缀 storage key |
双门禁已接入 build:
```bash
npm run build # = tsc -b && npm run check:styles && npm run check:independence && vite build
```
日常可单独运行:
```bash
npm run check:independence # 退出码 0 = 无全局 DOM / Portal / 无前缀 storage 违规
```
---
## 6. 代码适配
### 6.1 入口与 Provider
```tsx
// App.tsx 末尾:平台路由直接渲染默认导出,Provider 职责从 main.tsx 移到这里
import { AppProvider } from './app/store'
export default function App() {
return (
<AppProvider>
<AppShell />
</AppProvider>
)
}
```
同时把源 `main.tsx` 的 CSS import 全部搬到模块 `App.tsx` 顶部(保持原有顺序)。
### 6.2 严格 tsconfig 适配(tsc -b 报错清单)
- `TS6133` 未使用变量/import → 删除(含解构中未使用的成员)
- `TS2554`:`useRef<T>()` → `useRef<T | undefined>(undefined)`(@types/react 19 要求初始值)
- 默认导入 `import React` 未使用 → 删除(react-jsx transform 无需)
### 6.3 其他常见点
- 事件监听/定时器在组件卸载时清理(模块可被随时切走)
- 弹窗内 `dangerouslySetInnerHTML` 注入的 HTML,其类名也要被命名空间 CSS 覆盖(确认前缀后仍能匹配)
- 内部 state 切页的项目保留原交互,不强行改造为 URL 路由
---
## 7. 平台注册(三件套 + 图标)
```ts
// 1. src/modules/<name>/index.ts
import type { ModuleConfig } from '../registry';
export const moduleConfig: ModuleConfig = {
id: '<name>',
name: '模块中文名',
description: '一句话描述',
icon: 'Lucide图标名', // 如 FileSpreadsheet / Radar / Building2
path: '/<name>',
accentColor: '#7C6FFF', // 暗色强调色
accentColorLight: '#5747EF', // 亮色强调色
gradient: 'linear-gradient(135deg, ...)', // 暗色卡片渐变
gradientLight: 'linear-gradient(135deg, ...)', // 亮色卡片渐变
tags: ['标签1', '标签2'],
};
```
```ts
// 2. src/modules/registry.ts:import + modules 数组追加
// 3. src/App.tsx:模块级 React.lazy 动态导入 + 路由(ModuleTitle 负责页签标题,卸载恢复 'EIOSpace')
const XxxApp = lazy(() => import('@/modules/<name>/App'));
...
<Routes>
<Suspense fallback={<ModuleLoading />}>
<Route path="/<name>" element={<RequireAuth><ModuleTitle title="模块中文名"><XxxApp /></ModuleTitle></RequireAuth>} />
...
</Suspense>
</Routes>
// 4. src/pages/HomePage.tsx:ICON_MAP 增加图标(先在 lucide-react import 中补图标名)
```
> 模块入口必须用 `React.lazy` 动态导入(模块 CSS 随路由 chunk 按需加载),**静态 import 会把模块 CSS 打进主包,禁止**。
> 首页卡片点击已是 `window.open(mod.path, '_blank')` 新页签打开,无需额外处理。
---
## 8. 验证清单
**构建层**
- [ ] `npx tsc --noEmit` 通过
- [ ] `npm run build` 通过(注意 `tsc -b` 比 `tsc --noEmit` 更严,以 build 为准;已含 `check:styles` + `check:independence` 双门禁)
- [ ] `npm run check:styles` 退出码 0(模块 CSS 全局选择器零容忍门禁,见 §4.5,已接入 build)
- [ ] `npm run check:independence` 退出码 0(全局 DOM 写入 / body Portal / 无前缀 storage key 零容忍门禁,见 §5.9,已接入 build)
- [ ] `dist/mod-assets/<name>/` 资源齐全
- [ ] **`ls dist/` 确认根目录下没有与模块路由同名的目录**(防端口泄漏,见 §3)
**浏览器层**(dev server + mock 登录)
```js
// 平台守卫只查 sessionStorage.userToken,浏览器验证先注入:
sessionStorage.setItem('userToken', 'mock-token-for-ui-check');
sessionStorage.setItem('userInfo', JSON.stringify({ name: '演示用户', userId: 'demo' }));
```
- [ ] `/<name>` 页面完整渲染(header/侧栏/内容区),控制台无 React 报错、无 404
- [ ] 页内交互可用(菜单切换、弹窗、主题切换)
- [ ] 新页签打开后浏览器标题为模块中文名
- [ ] 首页出现新模块卡片(图标、配色正确)
- [ ] 首页(未进入任何模块)Network 面板无任何模块级 CSS chunk
- [ ] 首次进入模块路由时按需加载对应 JS+CSS chunk(React.lazy 生效)
- [ ] **进入模块再返回首页,首页视觉无污染**(body class/style 无残留、CSS 变量无残留、无 Portal 残留 DOM)
- [ ] **弹窗/抽屉等 Portal 的 DOM 位于模块根容器内部**(Elements 面板检查,非 `document.body` 直接子节点)
**回归层(改了旧模块 CSS 时必做)**
- [ ] 新模块关键布局 computed style 复核(如 nav 的 display)
- [ ] 被 CSS 影响的旧模块核心页面正常(如 supplier 顶栏导航)
- [ ] 平台首页/登录页样式未受污染
---
## 9. 部署注意(nginx)
- `nginx.conf` SPA 回退必须是 `try_files $uri /index.html;`——**禁止 `$uri/`**(目录命中 → 403 且不回退)
- **必须加两条重定向加固**(防止容器内端口泄漏到浏览器地址栏,2026-10 事故根因):
```nginx
server {
listen 8901;
...
port_in_redirect off; # 301 重定向的 Location 不带 8901 端口
absolute_redirect off; # 使用相对路径 Location,彻底避免泄漏 host/port
}
```
- 部署后用生产地址冒烟验证(新页签打开路径):
```bash
curl -sI https://ai-workshop.digiwincloud.com.cn/<name> | head -5
# 期望:HTTP 200(或 302 跳登录页)
# 异常信号:HTTP 301 且 Location 带 :8901 —— 即存在与路由同名的静态目录触发了目录重定向
```
- 模块静态资源引用用绝对路径 `/mod-assets/...`,与部署子路径无关
---
## 10. 历史踩坑速查表
| 案例 | 坑 | 修复 |
|---|---|---|
| baode-web ↔ supplier-platform | baode 自检页 `.page{max-width:1080px}` 污染 supplier 的 `section.page` | `.page`→`.checkpage` + 冲突类加 `.baode-root` 前缀 |
| supplier-platform | 源 tsconfig 宽松,`useRef<T>()` 在 @types/react 19 下报 TS2554 | `useRef<T \| undefined>(undefined)` |
| 全部模块 | dist 下与路由同名目录:早期 `try_files $uri/` 命中目录 403;去掉 `$uri/` 后 `$uri` 仍命中目录触发 301 补斜杠,`port_in_redirect` 默认 on 把容器端口 `:8901` 泄漏进浏览器地址栏,新页签跳到带端口地址后 403/空白 | 资源统一迁 `mod-assets/`;nginx 加 `port_in_redirect off; absolute_redirect off;` |
| wuc-quotation | 漏迁 `AppProvider` → 白屏 `ctx is null` | Provider 移入模块默认导出 |
| wuc-quotation | 001.css 7.8MB 内嵌 data URI + minified,正则替换会破坏资产 | 状态机解析转换,字符串原样保留 |
| wuc-quotation | `document.body.classList.toggle('dark')` 污染平台 body | 改挂 `.wuc-root` 根容器 ref |
| wuc-quotation | `@media` 内规则未递归前缀化(首版转换脚本 bug) | 递归处理 + 转换后自动校验 |
| wuc-quotation ↔ supplier-platform | `#nav` ID 特异性碾压类前缀,菜单被改 flex 水平 | 旧模块规则改 `.hansong-app #nav`;SOP 增加 ID 冲突检测 |
| jieya-ibp / welltrust-qap | sql.js wasm 路径、logo 相对路径失效 | 统一 `locateFile: () => '/mod-assets/<name>/...'` |
| 全部模块 | 模块 CSS 全局选择器(`:root`/`button`/`table`/`::-webkit-scrollbar`/`*`)跨模块污染 | 加模块根容器前缀 + `check:styles` 门禁(§4.5,已接入 build) |