Files
2026-10-18 21:41:09 +08:00

3.1 KiB
Raw Permalink Blame History

name, description
name description
react-module-integration 将独立 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/<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 路由 + HomePage.tsx ICON_MAP 四件套。
  7. 验证(SOP §7):构建层、浏览器层(mock 登录注入)、回归层逐项打勾。
  8. 部署检查(SOP §8):nginx 加固与生产地址冒烟。

红线(违反必出事故)

  • 路由与资源目录永不同名:资源只放 public/mod-assets/<name>/,绝不能放 public/<name>/。否则 dist 下出现与路由同名目录,nginx 目录 301 补斜杠并把容器端口 :8901 泄漏进浏览器地址栏,新页签 403/空白(2026-10 生产事故,SOP §3、§8)。
  • 样式绝对隔离:所有 CSS 选择器挂模块根容器类下,平台各模块 CSS 全局共载,裸选择器必然跨模块污染;ID 选择器特异性最高,#nav 类冲突需给旧模块规则也加前缀(SOP §4.2)。
  • 零平台侵入:不改 document.body/document.documentElement,存储 key 带模块前缀,不与平台路由冲突。
  • Provider 必须迁移:漏迁 AppProvider 会导致路由渲染时 context 为 null 白屏。

验证捷径

  • 构建后 ls dist/ 确认根目录无与路由同名目录。
  • 部署后 curl -sI https://生产域名/<name> 期望 200(或 302 跳登录);出现 301 且 Location 带 :8901 即端口泄漏信号。
  • 浏览器验证前先注入 mock 会话:sessionStorage.setItem('userToken', 'mock-token-for-ui-check')。

历史踩坑速查

详见 SOP §9 速查表。最高频三坑:同名资源目录端口泄漏、#nav ID 冲突、漏迁 Provider。