From 2a34c942688358ea83e55b4195bdfdf506cd6af2 Mon Sep 17 00:00:00 2001 From: dongsk Date: Sun, 18 Oct 2026 21:38:01 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E8=9E=8D=E5=90=88=E7=BB=8F?= =?UTF-8?q?=E9=AA=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/react-module-integration-sop.md | 256 +++++++++++++++++++++++++++ 1 file changed, 256 insertions(+) create mode 100644 docs/react-module-integration-sop.md diff --git a/docs/react-module-integration-sop.md b/docs/react-module-integration-sop.md new file mode 100644 index 0000000..25a7390 --- /dev/null +++ b/docs/react-module-integration-sop.md @@ -0,0 +1,256 @@ +# React 前端项目融合 ai-platform 模块化 SOP + +> 适用场景:将独立的 React 前端项目(Vite 构建)融合进 `ai-platform`,作为首页可进入的独立模块。 +> 已按此 SOP 成功融合:jieya-ibp、welltrust-qap、baode-web、supplier-platform、wuc-quotation。 + +--- + +## 0. 核心原则(先记住这四条) + +1. **样式绝对隔离**:平台所有模块的 CSS 会同时全局加载(静态 import,无懒加载隔离),任何裸元素选择器、`:root`/`body` 全局规则、裸 class/ID 选择器都会跨模块污染。**模块所有 CSS 选择器必须挂在模块根容器类下**。 +2. **路由与资源目录永不同名**:模块路由名(如 `/wuc-quotation`)绝不能与 `dist` 下静态资源目录同名,否则 nginx `try_files $uri` 命中目录触发自动 301 补斜杠重定向,Location 会带上容器内端口(8901)泄漏进浏览器地址栏,随后 403(详见 §3、§8)。资源统一放 `public/mod-assets/<模块名>/`。 +3. **零平台侵入**:模块不得修改 `document.body`/`document.documentElement` 的 class/style,不得占用全局 localStorage key,不得与平台路由冲突。 +4. **入口职责迁移**:源项目 `main.tsx` 中的 Provider 包裹、全局 CSS 引入等职责,全部迁移到模块 `App.tsx`,平台路由直接渲染模块默认导出。 + +--- + +## 1. 前期勘察(融合前必做,约 10 分钟) + +对源项目逐项检查并记录结论: + +| 检查项 | 命令/方法 | 判定 | +|---|---|---| +| 新增依赖 | 对比 `package.json` 与 ai-platform | 原则上零新增;有新增需评估版本冲突 | +| 路由方式 | 看源 `main.tsx`/`App.tsx` | URL 子路由 → 平台路由用 `/xxx/*`;内部 state 切页 → 精确 path 即可 | +| 入口 Provider | 看 `main.tsx` 的 `` 包裹 | **必须迁移**(否则路由渲染时 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,注意类型差异(见 §5.3) | + +--- + +## 2. 目录规划与代码复制 + +``` +ai-platform/ +├── src/modules// # 模块源码 +│ ├── App.tsx # 入口(含 Provider 包裹 + CSS 引入 + 根容器) +│ ├── index.ts # moduleConfig 导出 +│ ├── app/ | pages/ | ... # 源项目 src 业务代码(排除 main.tsx、__tests__) +│ └── styles/ | *.css # 源项目样式 +└── public/mod-assets// # 模块静态资源(禁止放 public//) +``` + +```bash +mkdir -p ai-platform/src/modules/ ai-platform/public/mod-assets/ +cp -R <源项目>/src/app ai-platform/src/modules//app +cp -R <源项目>/src/styles ai-platform/src/modules//styles +cp <源项目>/src/App.tsx ai-platform/src/modules//App.tsx +# 不要复制 main.tsx、__tests__、vite.config 等入口/测试文件 +``` + +--- + +## 3. 静态资源迁移 + +1. `public/` 下资源全部复制到 `public/mod-assets//`; +2. grep 源码中所有相对路径引用(`src="xxx.svg"`、`href="xxx.md"`、`locateFile` 等),统一改为绝对路径 `/mod-assets//xxx`; +3. 验证:dev 下直接访问 `http://localhost:/mod-assets//xxx` 返回 200; +4. build 后确认 `dist/mod-assets//` 存在。 + +> 为什么不用 `public//`:Vite 会把 public 目录原样拷入 dist,形成与模块路由同名的目录。完整故障链(2026-10 生产事故): +> 1. 首页卡片 `window.open('/')` → nginx `try_files $uri /index.html` 的 `$uri` 命中该**目录**(非文件); +> 2. nginx 对目录请求自动 301 补斜杠(`/`),且 `port_in_redirect` 默认为 on,Location 变成 `https://域名:8901//`——**容器内端口被泄漏到浏览器地址栏**; +> 3. `:8901` 在外网不可达/无该虚拟主机 → 目录又无 index.html → 最终 403 或空白。 +> 症状特征:只有"新增且带同名静态目录"的模块新页签打开异常(地址栏出现 `:8901`),老模块完全正常。 + +--- + +## 4. 样式隔离(核心,必须逐条执行) + +### 4.1 根容器命名空间 + +模块 App 最外层包一个根容器,所有 CSS 选择器挂到它下面: + +```tsx +// App.tsx +const rootRef = useRef(null) +return
...
+``` + +命名空间化有三种落地方式(按源项目 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 三类冲突源都要检测(缺一不可) + +```python +# 检测思路(对每个已存在模块 + 平台全局样式执行) +# 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 一律禁止) + +--- + +## 5. 代码适配 + +### 5.1 入口与 Provider + +```tsx +// App.tsx 末尾:平台路由直接渲染默认导出,Provider 职责从 main.tsx 移到这里 +import { AppProvider } from './app/store' + +export default function App() { + return ( + + + + ) +} +``` + +同时把源 `main.tsx` 的 CSS import 全部搬到模块 `App.tsx` 顶部(保持原有顺序)。 + +### 5.2 严格 tsconfig 适配(tsc -b 报错清单) + +- `TS6133` 未使用变量/import → 删除(含解构中未使用的成员) +- `TS2554`:`useRef()` → `useRef(undefined)`(@types/react 19 要求初始值) +- 默认导入 `import React` 未使用 → 删除(react-jsx transform 无需) + +### 5.3 其他常见点 + +- 事件监听/定时器在组件卸载时清理(模块可被随时切走) +- 弹窗内 `dangerouslySetInnerHTML` 注入的 HTML,其类名也要被命名空间 CSS 覆盖(确认前缀后仍能匹配) +- 内部 state 切页的项目保留原交互,不强行改造为 URL 路由 + +--- + +## 6. 平台注册(三件套 + 图标) + +```ts +// 1. src/modules//index.ts +import type { ModuleConfig } from '../registry'; + +export const moduleConfig: ModuleConfig = { + id: '', + name: '模块中文名', + description: '一句话描述', + icon: 'Lucide图标名', // 如 FileSpreadsheet / Radar / Building2 + path: '/', + accentColor: '#7C6FFF', // 暗色强调色 + accentColorLight: '#5747EF', // 亮色强调色 + gradient: 'linear-gradient(135deg, ...)', // 暗色卡片渐变 + gradientLight: 'linear-gradient(135deg, ...)', // 亮色卡片渐变 + tags: ['标签1', '标签2'], +}; +``` + +```ts +// 2. src/modules/registry.ts:import + modules 数组追加 +// 3. src/App.tsx:路由(ModuleTitle 负责页签标题,卸载恢复 'EIOSpace') +} /> +// 4. src/pages/HomePage.tsx:ICON_MAP 增加图标(先在 lucide-react import 中补图标名) +``` + +> 首页卡片点击已是 `window.open(mod.path, '_blank')` 新页签打开,无需额外处理。 + +--- + +## 7. 验证清单 + +**构建层** +- [ ] `npx tsc --noEmit` 通过 +- [ ] `npm run build` 通过(注意 `tsc -b` 比 `tsc --noEmit` 更严,以 build 为准) +- [ ] `dist/mod-assets//` 资源齐全 +- [ ] **`ls dist/` 确认根目录下没有与模块路由同名的目录**(防端口泄漏,见 §3) + +**浏览器层**(dev server + mock 登录) +```js +// 平台守卫只查 sessionStorage.userToken,浏览器验证先注入: +sessionStorage.setItem('userToken', 'mock-token-for-ui-check'); +sessionStorage.setItem('userInfo', JSON.stringify({ name: '演示用户', userId: 'demo' })); +``` +- [ ] `/` 页面完整渲染(header/侧栏/内容区),控制台无 React 报错、无 404 +- [ ] 页内交互可用(菜单切换、弹窗、主题切换) +- [ ] 新页签打开后浏览器标题为模块中文名 +- [ ] 首页出现新模块卡片(图标、配色正确) + +**回归层(改了旧模块 CSS 时必做)** +- [ ] 新模块关键布局 computed style 复核(如 nav 的 display) +- [ ] 被 CSS 影响的旧模块核心页面正常(如 supplier 顶栏导航) +- [ ] 平台首页/登录页样式未受污染 + +--- + +## 8. 部署注意(nginx) + +- `nginx.conf` SPA 回退必须是 `try_files $uri /index.html;`——**禁止 `$uri/`**(目录命中 → 403 且不回退) +- **必须加两条重定向加固**(防止容器内端口泄漏到浏览器地址栏,2026-10 事故根因): + +```nginx +server { + listen 8901; + ... + port_in_redirect off; # 301 重定向的 Location 不带 8901 端口 + absolute_redirect off; # 使用相对路径 Location,彻底避免泄漏 host/port +} +``` + +- 部署后用生产地址冒烟验证(新页签打开路径): + +```bash +curl -sI https://ai-workshop.digiwincloud.com.cn/ | head -5 +# 期望:HTTP 200(或 302 跳登录页) +# 异常信号:HTTP 301 且 Location 带 :8901 —— 即存在与路由同名的静态目录触发了目录重定向 +``` + +- 模块静态资源引用用绝对路径 `/mod-assets/...`,与部署子路径无关 + +--- + +## 9. 历史踩坑速查表 + +| 案例 | 坑 | 修复 | +|---|---|---| +| baode-web ↔ supplier-platform | baode 自检页 `.page{max-width:1080px}` 污染 supplier 的 `section.page` | `.page`→`.checkpage` + 冲突类加 `.baode-root` 前缀 | +| supplier-platform | 源 tsconfig 宽松,`useRef()` 在 @types/react 19 下报 TS2554 | `useRef(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//...'` |