Files
ai-platform/.trae/skills/react-module-integration/references/react-module-integration-sop.md
T
2026-11-19 11:02:39 +08:00

20 KiB
Raw Blame History

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>/)
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 选择器挂到它下面:

// 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 三类冲突源都要检测(缺一不可)

# 检测思路(对每个已存在模块 + 平台全局样式执行)
# 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),日常可单独运行:

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:

npm run build   # = tsc -b && npm run check:styles && npm run check:independence && vite build

日常可单独运行:

npm run check:independence   # 退出码 0 = 无全局 DOM / Portal / 无前缀 storage 违规

6. 代码适配

6.1 入口与 Provider

// 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. 平台注册(三件套 + 图标)

// 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'],
};
// 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 登录)

// 平台守卫只查 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 事故根因):
server {
    listen 8901;
    ...
    port_in_redirect off;    # 301 重定向的 Location 不带 8901 端口
    absolute_redirect off;   # 使用相对路径 Location,彻底避免泄漏 host/port
}
  • 部署后用生产地址冒烟验证(新页签打开路径):
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)