Files
ai-platform/docs/react-module-integration-sop.md
2026-10-18 21:38:01 +08:00

257 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 的 `<XxxProvider>` 包裹 | **必须迁移**(否则路由渲染时 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/<name>/ # 模块源码
│ ├── App.tsx # 入口(含 Provider 包裹 + CSS 引入 + 根容器)
│ ├── index.ts # moduleConfig 导出
│ ├── app/ | pages/ | ... # 源项目 src 业务代码(排除 main.tsx、__tests__)
│ └── styles/ | *.css # 源项目样式
└── public/mod-assets/<name>/ # 模块静态资源(禁止放 public/<name>/)
```
```bash
mkdir -p ai-platform/src/modules/<name> ai-platform/public/mod-assets/<name>
cp -R <源项目>/src/app ai-platform/src/modules/<name>/app
cp -R <源项目>/src/styles ai-platform/src/modules/<name>/styles
cp <源项目>/src/App.tsx ai-platform/src/modules/<name>/App.tsx
# 不要复制 main.tsx、__tests__、vite.config 等入口/测试文件
```
---
## 3. 静态资源迁移
1. `public/` 下资源全部复制到 `public/mod-assets/<name>/`;
2. grep 源码中所有相对路径引用(`src="xxx.svg"`、`href="xxx.md"`、`locateFile` 等),统一改为绝对路径 `/mod-assets/<name>/xxx`;
3. 验证:dev 下直接访问 `http://localhost:<port>/mod-assets/<name>/xxx` 返回 200;
4. build 后确认 `dist/mod-assets/<name>/` 存在。
> 为什么不用 `public/<name>/`:Vite 会把 public 目录原样拷入 dist,形成与模块路由同名的目录。完整故障链(2026-10 生产事故):
> 1. 首页卡片 `window.open('/<name>')` → nginx `try_files $uri /index.html` 的 `$uri` 命中该**目录**(非文件);
> 2. nginx 对目录请求自动 301 补斜杠(`/`),且 `port_in_redirect` 默认为 on,Location 变成 `https://域名:8901/<name>/`——**容器内端口被泄漏到浏览器地址栏**;
> 3. `:8901` 在外网不可达/无该虚拟主机 → 目录又无 index.html → 最终 403 或空白。
> 症状特征:只有"新增且带同名静态目录"的模块新页签打开异常(地址栏出现 `:8901`),老模块完全正常。
---
## 4. 样式隔离(核心,必须逐条执行)
### 4.1 根容器命名空间
模块 App 最外层包一个根容器,所有 CSS 选择器挂到它下面:
```tsx
// App.tsx
const rootRef = useRef<HTMLDivElement>(null)
return <div className="xxx-root" ref={rootRef}>...</div>
```
命名空间化有三种落地方式(按源项目 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 (
<AppProvider>
<AppShell />
</AppProvider>
)
}
```
同时把源 `main.tsx` 的 CSS import 全部搬到模块 `App.tsx` 顶部(保持原有顺序)。
### 5.2 严格 tsconfig 适配(tsc -b 报错清单)
- `TS6133` 未使用变量/import → 删除(含解构中未使用的成员)
- `TS2554`:`useRef<T>()` → `useRef<T | undefined>(undefined)`(@types/react 19 要求初始值)
- 默认导入 `import React` 未使用 → 删除(react-jsx transform 无需)
### 5.3 其他常见点
- 事件监听/定时器在组件卸载时清理(模块可被随时切走)
- 弹窗内 `dangerouslySetInnerHTML` 注入的 HTML,其类名也要被命名空间 CSS 覆盖(确认前缀后仍能匹配)
- 内部 state 切页的项目保留原交互,不强行改造为 URL 路由
---
## 6. 平台注册(三件套 + 图标)
```ts
// 1. src/modules/<name>/index.ts
import type { ModuleConfig } from '../registry';
export const moduleConfig: ModuleConfig = {
id: '<name>',
name: '模块中文名',
description: '一句话描述',
icon: 'Lucide图标名', // 如 FileSpreadsheet / Radar / Building2
path: '/<name>',
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')
<Route path="/<name>" element={<RequireAuth><ModuleTitle title="模块中文名"><XxxApp /></ModuleTitle></RequireAuth>} />
// 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/<name>/` 资源齐全
- [ ] **`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' }));
```
- [ ] `/<name>` 页面完整渲染(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/<name> | 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<T>()` 在 @types/react 19 下报 TS2554 | `useRef<T \| undefined>(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/<name>/...'` |