新增融合skill

This commit is contained in:
2026-10-18 21:41:09 +08:00
parent 2a34c94268
commit 4e2459f2c8
2 changed files with 292 additions and 0 deletions
@@ -0,0 +1,36 @@
---
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/<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。