3.6 KiB
3.6 KiB
name, description
| name | description |
|---|---|
| react-module-integration | 将独立 React(Vite) 前端项目融合进 ai-platform 平台成为首页可进入的模块,覆盖前期勘察、静态资源迁移、CSS 样式隔离、平台注册与验证部署全流程。当用户要求把 React 项目接入或融合进 ai-platform、新增平台模块、排查模块融合后白屏或部署异常时使用。不用于从零新建独立项目或纯后端接入。 |
ai-platform React 模块融合
完整操作手册在 references/react-module-integration-sop.md(含命令、代码模板、案例),执行任何一步前先阅读对应章节。以下为必须遵守的红线与执行顺序。
执行顺序
- 前期勘察(SOP §1):对源项目逐项检查——新增依赖、路由方式、入口 Provider、全局 CSS、
document.body操作、public 资源清单、存储 key 前缀、@keyframes命名、React 版本差异。 - 目录规划与复制(SOP §2):源码进
src/modules/<name>/,禁止复制main.tsx、__tests__。 - 静态资源迁移(SOP §3):资源统一放
public/mod-assets/<name>/,代码引用全部改为绝对路径/mod-assets/<name>/xxx(含locateFile)。 - 样式隔离(SOP §4):模块根容器类(如
.xxx-root)作为所有选择器前缀;body/:root/html/#root规则必须改写或删除;class、ID、裸元素三类冲突源都要检测。 - 代码适配(SOP §5):源
main.tsx的 Provider 包裹与 CSS import 全部迁入模块App.tsx;tsc -b报错按清单修(TS6133、TS2554)。 - 平台注册(SOP §6):
moduleConfig+registry.ts+App.tsx路由(模块用React.lazy动态导入 +<Suspense fallback={<ModuleLoading />}>包<Routes>,禁止静态 import,否则模块 CSS 进主包)+HomePage.tsxICON_MAP 四件套。 - 验证(SOP §7):构建层、浏览器层(mock 登录注入)、回归层逐项打勾。
- 部署检查(SOP §8):nginx 加固与生产地址冒烟。
红线(违反必出事故)
- 路由与资源目录永不同名:资源只放
public/mod-assets/<name>/,绝不能放public/<name>/。否则 dist 下出现与路由同名目录,nginx 目录 301 补斜杠并把容器端口:8901泄漏进浏览器地址栏,新页签 403/空白(2026-10 生产事故,SOP §3、§8)。 - 样式绝对隔离:所有 CSS 选择器挂模块根容器类下。模块 CSS 虽随 React.lazy 路由 chunk 按需加载,但加载后仍全局生效,裸选择器必然跨模块污染;同名
@keyframes/工具类若值不同必须重命名或作用域化。全局选择器由npm run check:styles零容忍门禁拦截(已接入 build,SOP §4.5);ID 选择器特异性最高,#nav类冲突需给旧模块规则也加前缀(SOP §4.2)。 - 零平台侵入:不改
document.body/document.documentElement,存储 key 带模块前缀,不与平台路由冲突。 - Provider 必须迁移:漏迁
AppProvider会导致路由渲染时 context 为 null 白屏。
验证捷径
- 提交/构建前跑
npm run check:styles(已接入 build 门禁),退出码 0 = 模块 CSS 无全局选择器违规。 - 构建后
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。