Compare commits
3
Commits
8f6904b2d1
...
develop
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
90ee2b30f5 | ||
|
|
4e2459f2c8 | ||
|
|
2a34c94268 |
@@ -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。
|
||||||
@@ -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` 的 `<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>/...'` |
|
||||||
@@ -0,0 +1,12 @@
|
|||||||
|
# Checklist
|
||||||
|
- [ ] `src/App.tsx` 全部模块组件改为 `React.lazy()` 动态导入,`<Suspense>` 兜底生效
|
||||||
|
- [ ] `npx tsc -b` 类型检查通过
|
||||||
|
- [ ] `npm run build` 成功,`dist/assets` 中每个模块的 CSS 为独立 chunk 文件
|
||||||
|
- [ ] `scripts/check-module-styles.mjs` 存在且能正确检测 `:root`/`html`/`body`/`*`/裸元素选择器/`@import` 重置,违规时非 0 退出并列出文件+行号
|
||||||
|
- [ ] `package.json` 含 `check:styles` 脚本,且 `build` 脚本已接入该门禁
|
||||||
|
- [ ] `bomx-reuse-analyzer/styles.css` 无 `:root` 残留,模块页面 CSS 变量取值正常、视觉无回归
|
||||||
|
- [ ] `npm run check:styles` 退出码 0
|
||||||
|
- [ ] 首页加载时 Network 面板无任何模块级 CSS chunk
|
||||||
|
- [ ] 跳转 `supplier-platform`/`wuc-quotation`/`bomx-reuse-analyzer` 时按需加载对应样式且渲染正常、无控制台报错
|
||||||
|
- [ ] 平台首页与登录页视觉未受模块样式污染
|
||||||
|
- [ ] `docs/react-module-integration-sop.md` 与 `.trae/skills/react-module-integration/SKILL.md` 已包含 lazy 路由约定与 check:styles 校验说明
|
||||||
@@ -0,0 +1,70 @@
|
|||||||
|
# 模块样式隔离与按需加载 Spec
|
||||||
|
|
||||||
|
## Why
|
||||||
|
当前 `src/App.tsx` 静态 import 全部 12 个模块的 App 组件,导致所有模块的 JS 与 CSS 全部打进主包,用户打开首页即下载全部模块样式(wuc-quotation 单个模块 CSS 约 7.8MB)。同时样式隔离仅依赖 SOP 中的手工命名空间约定,无自动化守护,仍存在残留全局选择器(如 `bomx-reuse-analyzer/styles.css` 的 `:root` 规则)可跨模块污染。
|
||||||
|
|
||||||
|
## What Changes
|
||||||
|
- **路由级懒加载**:`src/App.tsx` 中模块组件改为 `React.lazy()` 动态导入,外层包 `<Suspense>` 加载兜底;Vite 自动将每个模块拆为独立 JS+CSS chunk,仅在跳转到对应路由时才加载该模块样式。
|
||||||
|
- **样式隔离自动化守护**:新增 `scripts/check-module-styles.mjs` 检查脚本,扫描 `src/modules/**/*.css` 中的全局选择器(`:root`/`html`/`body`/`*`/裸元素选择器/`@import` 全局重置),发现违规即报错退出;注册为 `npm run check:styles`。
|
||||||
|
- **修复存量违规**:`bomx-reuse-analyzer/styles.css` 的 `:root` CSS 变量迁移到模块根容器类下。
|
||||||
|
- **构建管线接入**:存量违规清零后,将 `check:styles` 纳入 `build` 脚本,防止后续模块引入全局选择器。
|
||||||
|
- **文档同步**:更新 SOP 文档与 react-module-integration 技能,明确新模块接入必须使用 lazy 路由模式 + 命名空间根容器。
|
||||||
|
|
||||||
|
## Impact
|
||||||
|
- Affected specs: 无既有 spec(首次建立)
|
||||||
|
- Affected code:
|
||||||
|
- `src/App.tsx`(懒加载改造)
|
||||||
|
- `src/modules/bomx-reuse-analyzer/styles.css`(存量违规修复)
|
||||||
|
- `scripts/check-module-styles.mjs`(新增)
|
||||||
|
- `package.json`(新增 check:styles 脚本、build 接入)
|
||||||
|
- `docs/react-module-integration-sop.md`、`.trae/skills/react-module-integration/SKILL.md`(文档同步)
|
||||||
|
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: 模块按需加载
|
||||||
|
系统 SHALL 以 `React.lazy()` 动态导入方式注册全部模块路由,保证模块代码与样式拆分为独立 chunk,仅在用户导航至该模块路由时才发起加载。
|
||||||
|
|
||||||
|
#### Scenario: 首页不加载模块样式
|
||||||
|
- **WHEN** 用户登录后停留在平台首页(`/`)
|
||||||
|
- **THEN** Network 面板中不出现任何模块级 CSS chunk(如 `wuc-quotation`、`supplier-platform` 的 CSS 文件)
|
||||||
|
|
||||||
|
#### Scenario: 跳转模块时加载对应样式
|
||||||
|
- **WHEN** 用户首次导航到某模块路由(如 `/supplier-platform`)
|
||||||
|
- **THEN** 浏览器按需加载该模块对应的 JS 与 CSS chunk,模块界面正常渲染
|
||||||
|
|
||||||
|
#### Scenario: 加载期间兜底 UI
|
||||||
|
- **WHEN** 模块 chunk 尚在加载中
|
||||||
|
- **THEN** Suspense 兜底占位展示(平台风格的加载提示),加载完成后无报错切换至模块界面
|
||||||
|
|
||||||
|
#### Scenario: 构建产物按模块拆分
|
||||||
|
- **WHEN** 执行 `npm run build`
|
||||||
|
- **THEN** `dist/assets` 中每个模块生成独立的 JS 与 CSS 产物(含路由引用关系),`tsc -b` 类型检查通过
|
||||||
|
|
||||||
|
### Requirement: 模块样式全局选择器零容忍
|
||||||
|
系统 SHALL 提供自动化检查脚本,确保 `src/modules/**/*.css` 中不出现全局作用选择器;检查结果 SHALL 作为构建门禁。
|
||||||
|
|
||||||
|
#### Scenario: 扫描通过
|
||||||
|
- **WHEN** 执行 `npm run check:styles` 且所有模块 CSS 均挂在模块命名空间根容器类下
|
||||||
|
- **THEN** 脚本以退出码 0 结束,无违规输出
|
||||||
|
|
||||||
|
#### Scenario: 扫描发现违规
|
||||||
|
- **WHEN** 某模块 CSS 中存在 `:root`、`html`、`body`、`*`、裸元素选择器或 `@import` 全局重置
|
||||||
|
- **THEN** 脚本以非 0 退出码失败,并逐条输出违规文件、行号与选择器内容
|
||||||
|
|
||||||
|
#### Scenario: 构建门禁生效
|
||||||
|
- **WHEN** 模块 CSS 存在全局选择器违规时执行 `npm run build`
|
||||||
|
- **THEN** 构建失败并提示先修复样式违规
|
||||||
|
|
||||||
|
### Requirement: 存量违规清零
|
||||||
|
系统 SHALL 保证现有 12 个模块 CSS 无全局选择器残留,不污染平台首页、登录页及其它模块。
|
||||||
|
|
||||||
|
#### Scenario: bomx-reuse-analyzer 变量迁移
|
||||||
|
- **WHEN** `src/modules/bomx-reuse-analyzer/styles.css` 中存在 `:root { --xxx }` 规则
|
||||||
|
- **THEN** 变量定义迁移至该模块根容器类下,模块页面变量取值正常,视觉无回归
|
||||||
|
|
||||||
|
### Requirement: 新模块接入约定同步
|
||||||
|
SOP 文档与 react-module-integration 技能 SHALL 同步更新:新模块路由必须使用 lazy 动态导入模式,CSS 必须挂载在模块命名空间根容器下,并通过 check:styles 校验。
|
||||||
|
|
||||||
|
#### Scenario: 文档含懒加载约定
|
||||||
|
- **WHEN** 查阅 SOP 文档或技能文件
|
||||||
|
- **THEN** 可找到 lazy 路由模式代码约定与 check:styles 校验说明
|
||||||
@@ -0,0 +1,25 @@
|
|||||||
|
# Tasks
|
||||||
|
- [ ] Task 1: 路由级懒加载改造
|
||||||
|
- [ ] SubTask 1.1: `src/App.tsx` 将 12 个模块组件的静态 import 全部改为 `React.lazy(() => import('...'))`
|
||||||
|
- [ ] SubTask 1.2: `<Routes>` 外层包 `<Suspense>`,提供平台风格 loading 兜底(居中 spinner + "模块加载中"文案)
|
||||||
|
- [ ] SubTask 1.3: 验证 `npx tsc -b` 类型检查通过;`npm run build` 后确认 `dist/assets` 中各模块 CSS 拆分为独立文件
|
||||||
|
- [ ] Task 2: 样式隔离自动检查脚本
|
||||||
|
- [ ] SubTask 2.1: 新增 `scripts/check-module-styles.mjs`:递归扫描 `src/modules/**/*.css`,检测 `:root`/`html`/`body`/`*` 选择器、裸元素选择器(无类/ID/命名空间前缀的元素标签规则)、`@import` 全局重置;违规输出文件+行号+选择器,非 0 退出
|
||||||
|
- [ ] SubTask 2.2: `package.json` 注册 `"check:styles": "node scripts/check-module-styles.mjs"`
|
||||||
|
- [ ] Task 3: 修复存量违规
|
||||||
|
- [ ] SubTask 3.1: `src/modules/bomx-reuse-analyzer/styles.css` 的 `:root { --xxx }` 变量迁移至模块根容器类;核对 `BomxReuseHome.tsx` 根容器类名并确认页面变量取值正常
|
||||||
|
- [ ] SubTask 3.2: `npm run check:styles` 退出码 0(存量违规清零)
|
||||||
|
- [ ] Task 4: 构建门禁与文档同步
|
||||||
|
- [ ] SubTask 4.1: `package.json` 的 `build` 脚本接入 `check:styles`(`tsc -b && npm run check:styles && vite build`)
|
||||||
|
- [ ] SubTask 4.2: 更新 `docs/react-module-integration-sop.md`:新增「路由必须 lazy 动态导入」约定与 check:styles 校验说明
|
||||||
|
- [ ] SubTask 4.3: 同步 `.trae/skills/react-module-integration/SKILL.md`(红线与验证清单补充懒加载要求)
|
||||||
|
- [ ] Task 5: 端到端验证
|
||||||
|
- [ ] SubTask 5.1: `npm run dev` 启动,浏览器验证:首页 Network 无任何模块 CSS chunk
|
||||||
|
- [ ] SubTask 5.2: 依次跳转 `supplier-platform`、`wuc-quotation`、`bomx-reuse-analyzer`:按需加载对应 chunk、界面渲染正常、无控制台报错
|
||||||
|
- [ ] SubTask 5.3: 抽查首页与登录页视觉无污染、`bomx-reuse-analyzer` 页面样式无回归
|
||||||
|
|
||||||
|
# Task Dependencies
|
||||||
|
- Task 3 依赖 Task 2(需要脚本先检测出违规)
|
||||||
|
- Task 4 依赖 Task 2、Task 3(违规清零后才接入构建门禁)
|
||||||
|
- Task 5 依赖 Task 1(懒加载完成后方可验证按需加载);SubTask 5.3 依赖 Task 3
|
||||||
|
- Task 2 与 Task 1 无依赖,可并行
|
||||||
@@ -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` 的 `<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>/...'` |
|
||||||
Reference in New Issue
Block a user