# 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` 的 `` 包裹 | **必须迁移**(否则路由渲染时 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// # 模块源码 │ ├── App.tsx # 入口(含 Provider 包裹 + CSS 引入 + 根容器) │ ├── index.ts # moduleConfig 导出 │ ├── app/ | pages/ | ... # 源项目 src 业务代码(排除 main.tsx、__tests__) │ └── styles/ | *.css # 源项目样式 └── public/mod-assets// # 模块静态资源(禁止放 public//) ``` ```bash mkdir -p ai-platform/src/modules/ ai-platform/public/mod-assets/ cp -R <源项目>/src/app ai-platform/src/modules//app cp -R <源项目>/src/styles ai-platform/src/modules//styles cp <源项目>/src/App.tsx ai-platform/src/modules//App.tsx # 不要复制 main.tsx、__tests__、vite.config 等入口/测试文件 ``` --- ## 3. 静态资源迁移 1. `public/` 下资源全部复制到 `public/mod-assets//`; 2. grep 源码中所有相对路径引用(`src="xxx.svg"`、`href="xxx.md"`、`locateFile` 等),统一改为绝对路径 `/mod-assets//xxx`; 3. 验证:dev 下直接访问 `http://localhost:/mod-assets//xxx` 返回 200; 4. build 后确认 `dist/mod-assets//` 存在。 > 为什么不用 `public//`:Vite 会把 public 目录原样拷入 dist,形成与模块路由同名的目录。完整故障链(2026-10 生产事故): > 1. 首页卡片 `window.open('/')` → nginx `try_files $uri /index.html` 的 `$uri` 命中该**目录**(非文件); > 2. nginx 对目录请求自动 301 补斜杠(`/`),且 `port_in_redirect` 默认为 on,Location 变成 `https://域名:8901//`——**容器内端口被泄漏到浏览器地址栏**; > 3. `:8901` 在外网不可达/无该虚拟主机 → 目录又无 index.html → 最终 403 或空白。 > 症状特征:只有"新增且带同名静态目录"的模块新页签打开异常(地址栏出现 `:8901`),老模块完全正常。 --- ## 4. 样式隔离(核心,必须逐条执行) ### 4.1 根容器命名空间 模块 App 最外层包一个根容器,所有 CSS 选择器挂到它下面: ```tsx // App.tsx const rootRef = useRef(null) return
...
``` 命名空间化有三种落地方式(按源项目 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` 注入 ``、`