diff --git a/.trae/skills/react-module-integration/SKILL.md b/.trae/skills/react-module-integration/SKILL.md index 421bde7..07c829f 100644 --- a/.trae/skills/react-module-integration/SKILL.md +++ b/.trae/skills/react-module-integration/SKILL.md @@ -13,25 +13,28 @@ description: 将独立 React(Vite) 前端项目融合进 ai-platform 平台成 2. **目录规划与复制**(SOP §2):源码进 `src/modules//`,禁止复制 `main.tsx`、`__tests__`。 3. **静态资源迁移**(SOP §3):资源统一放 `public/mod-assets//`,代码引用全部改为绝对路径 `/mod-assets//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` 路由(模块用 `React.lazy` 动态导入 + `}>` 包 ``,禁止静态 import,否则模块 CSS 进主包)+ `HomePage.tsx` ICON_MAP 四件套。 -7. **验证**(SOP §7):构建层、浏览器层(mock 登录注入)、回归层逐项打勾。 -8. **部署检查**(SOP §8):nginx 加固与生产地址冒烟。 +5. **代码适配**(SOP §6):源 `main.tsx` 的 Provider 包裹与 CSS import 全部迁入模块 `App.tsx`;`tsc -b` 报错按清单修(TS6133、TS2554)。 +6. **平台注册**(SOP §7):`moduleConfig` + `registry.ts` + `App.tsx` 路由(模块用 `React.lazy` 动态导入 + `}>` 包 ``,禁止静态 import,否则模块 CSS 进主包)+ `HomePage.tsx` ICON_MAP 四件套。 +7. **验证**(SOP §8):构建层、浏览器层(mock 登录注入)、回归层逐项打勾。 +8. **部署检查**(SOP §9):nginx 加固与生产地址冒烟。 ## 红线(违反必出事故) -- **路由与资源目录永不同名**:资源只放 `public/mod-assets//`,绝不能放 `public//`。否则 dist 下出现与路由同名目录,nginx 目录 301 补斜杠并把容器端口 `:8901` 泄漏进浏览器地址栏,新页签 403/空白(2026-10 生产事故,SOP §3、§8)。 +- **路由与资源目录永不同名**:资源只放 `public/mod-assets//`,绝不能放 `public//`。否则 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://生产域名/` 期望 200(或 302 跳登录);出现 301 且 Location 带 `:8901` 即端口泄漏信号。 - 浏览器验证前先注入 mock 会话:`sessionStorage.setItem('userToken', 'mock-token-for-ui-check')`。 +- 进入模块再返回首页,确认 body class/style、CSS 变量、Portal DOM 无残留(视觉无污染)。 ## 历史踩坑速查 -详见 SOP §9 速查表。最高频三坑:同名资源目录端口泄漏、`#nav` ID 冲突、漏迁 Provider。 +详见 SOP §10 速查表。最高频三坑:同名资源目录端口泄漏、`#nav` ID 冲突、漏迁 Provider。 diff --git a/.trae/skills/react-module-integration/references/react-module-integration-sop.md b/.trae/skills/react-module-integration/references/react-module-integration-sop.md index c4ac7f2..214adce 100644 --- a/.trae/skills/react-module-integration/references/react-module-integration-sop.md +++ b/.trae/skills/react-module-integration/references/react-module-integration-sop.md @@ -5,12 +5,13 @@ --- -## 0. 核心原则(先记住这四条) +## 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、§8)。资源统一放 `public/mod-assets/<模块名>/`。 +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)。 --- @@ -29,7 +30,7 @@ | 内嵌资产 | grep `data:` | base64 data URI 无需处理 | | 存储 key | grep `localStorage`/`sessionStorage` | key 必须带项目前缀,无前缀需加 | | keyframes | grep `@keyframes` | 与全平台 CSS 比对命名唯一性 | -| React 版本 | `package.json` | 平台为 React 18.3 + @types/react 19,注意类型差异(见 §5.3) | +| React 版本 | `package.json` | 平台为 React 18.3 + @types/react 19,注意类型差异(见 §6.3) | --- @@ -125,7 +126,7 @@ return
...
### 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 && vite build`),日常可单独运行: +`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),日常可单独运行: ```bash npm run check:styles # 退出码 0 = 模块 CSS 无全局选择器违规 @@ -133,9 +134,78 @@ npm run check:styles # 退出码 0 = 模块 CSS 无全局选择器违规 --- -## 5. 代码适配 +## 5. 模组完全独立互不影响(全维度隔离) -### 5.1 入口与 Provider +模块在平台中是「挂载即用、卸载即净」的独立单元,任何逃逸到全局的副作用都会污染首页与其它模块。本节是样式隔离(§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` 注入 ``、`