新增融合skill
This commit is contained in:
@@ -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。
|
||||
Reference in New Issue
Block a user