Files
ai-platform/.trae/skills/react-module-integration/SKILL.md
T
dongskandClaude Sonnet 4.6 noreply@anthropic.com> 8699798ea5 feat: 模组全维度独立,消除全局 DOM/Portal/存储污染
- jieya-ibp/welltrust-qap ThemeContext 改为作用域容器承载 CSS 变量与背景色,不再写 document
- 删除 order-cost CostCockpit 对 documentElement 的死变量写入
- bomx Drawer createPortal 挂载点内移到 .bomx-app,移除 document.body 兜底
- knowledge-graph 拖拽 cursor 改为根容器 ref
- 新增 check-module-independence 门禁并接入 build
- SOP 与融合技能文档补充「模组完全独立互不影响」章节

Co-Authored-By: Claude Sonnet 4.6 noreply@anthropic.com>
2026-10-19 09:10:30 +08:00

4.4 KiB
Raw 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 §6):源 main.tsx 的 Provider 包裹与 CSS import 全部迁入模块 App.tsx;tsc -b 报错按清单修(TS6133、TS2554)。
  6. 平台注册(SOP §7):moduleConfig + registry.ts + App.tsx 路由(模块用 React.lazy 动态导入 + <Suspense fallback={<ModuleLoading />}> 包 <Routes>,禁止静态 import,否则模块 CSS 进主包)+ HomePage.tsx ICON_MAP 四件套。
  7. 验证(SOP §8):构建层、浏览器层(mock 登录注入)、回归层逐项打勾。
  8. 部署检查(SOP §9):nginx 加固与生产地址冒烟。

红线(违反必出事故)

  • 路由与资源目录永不同名:资源只放 public/mod-assets/<name>/,绝不能放 public/<name>/。否则 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://生产域名/<name> 期望 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。