--- name: react-module-integration description: 将独立 React(Vite) 前端项目融合进 ai-platform 平台成为首页可进入的模块,覆盖前期勘察、静态资源迁移、CSS 样式隔离、平台注册与验证部署全流程。当用户要求把 React 项目接入或融合进 ai-platform、新增平台模块、排查模块融合后白屏或部署异常时使用。不用于从零新建独立项目或纯后端接入。 --- # ai-platform React 模块融合 完整操作手册在 `references/react-module-integration-sop.md`(含命令、代码模板、案例),执行任何一步前先阅读对应章节。以下为必须遵守的红线与执行顺序。 ## 执行顺序 1. **前期勘察**(SOP §1):对源项目逐项检查——新增依赖、路由方式、入口 Provider、全局 CSS、`document.body` 操作、public 资源清单、存储 key 前缀、`@keyframes` 命名、React 版本差异。 2. **目录规划与复制**(SOP §2):源码进 `src/modules//`,禁止复制 `main.tsx`、`__tests__`。 3. **静态资源迁移**(SOP §3):资源统一放 `public/mod-assets//`,代码引用全部改为绝对路径 `/mod-assets//xxx`(含 `locateFile`)。 4. **样式隔离**(SOP §4):模块根容器类(如 `.xxx-root`)作为所有选择器前缀;`body`/`:root`/`html`/`#root` 规则必须改写或删除;class、ID、裸元素三类冲突源都要检测。 5. **代码适配**(SOP §6):源 `main.tsx` 的 Provider 包裹与 CSS import 全部迁入模块 `App.tsx`;`tsc -b` 报错按清单修(TS6133、TS2554)。 6. **平台注册**(SOP §7):`moduleConfig` + `registry.ts` + `App.tsx` 路由(模块用 `React.lazy` 动态导入 + `}>` 包 ``,禁止静态 import,否则模块 CSS 进主包)+ `HomePage.tsx` ICON_MAP 四件套。 7. **验证**(SOP §8):构建层、浏览器层(mock 登录注入)、回归层逐项打勾。 8. **部署检查**(SOP §9):nginx 加固与生产地址冒烟。 ## 红线(违反必出事故) - **路由与资源目录永不同名**:资源只放 `public/mod-assets//`,绝不能放 `public//`。否则 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://生产域名/` 期望 200(或 302 跳登录);出现 301 且 Location 带 `:8901` 即端口泄漏信号。 - 浏览器验证前先注入 mock 会话:`sessionStorage.setItem('userToken', 'mock-token-for-ui-check')`。 - 进入模块再返回首页,确认 body class/style、CSS 变量、Portal DOM 无残留(视觉无污染)。 ## 历史踩坑速查 详见 SOP §10 速查表。最高频三坑:同名资源目录端口泄漏、`#nav` ID 冲突、漏迁 Provider。