Compare commits
1
Commits
deveop
..
8699798ea5
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
8699798ea5 |
@@ -13,25 +13,28 @@ description: 将独立 React(Vite) 前端项目融合进 ai-platform 平台成
|
||||
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` 路由(模块用 `React.lazy` 动态导入 + `<Suspense fallback={<ModuleLoading />}>` 包 `<Routes>`,禁止静态 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` 动态导入 + `<Suspense fallback={<ModuleLoading />}>` 包 `<Routes>`,禁止静态 import,否则模块 CSS 进主包)+ `HomePage.tsx` ICON_MAP 四件套。
|
||||
7. **验证**(SOP §8):构建层、浏览器层(mock 登录注入)、回归层逐项打勾。
|
||||
8. **部署检查**(SOP §9):nginx 加固与生产地址冒烟。
|
||||
|
||||
## 红线(违反必出事故)
|
||||
|
||||
- **路由与资源目录永不同名**:资源只放 `public/mod-assets/<name>/`,绝不能放 `public/<name>/`。否则 dist 下出现与路由同名目录,nginx 目录 301 补斜杠并把容器端口 `:8901` 泄漏进浏览器地址栏,新页签 403/空白(2026-10 生产事故,SOP §3、§8)。
|
||||
- **路由与资源目录永不同名**:资源只放 `public/mod-assets/<name>/`,绝不能放 `public/<name>/`。否则 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://生产域名/<name>` 期望 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。
|
||||
|
||||
@@ -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 <div className="xxx-root" ref={rootRef}>...</div>
|
||||
|
||||
### 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` 注入 `<link>`、`<style>`、`<script>` 标签。
|
||||
- 需要锁滚动、切主题等副作用时,一律作用于模块根容器 `ref`,并在卸载时恢复。
|
||||
|
||||
### 5.4 存储 key 必须带模块前缀
|
||||
|
||||
- localStorage / sessionStorage 的 key 必须带模块前缀(如 `wuchuan-quotation-v1`、`sp_theme`、`ocDataSourceMode`、`welltrust-qap-*` 等)。
|
||||
- **白名单**:平台级 `userToken`、`userInfo` 可直接读写,模块不得新增其它无前缀全局 key。
|
||||
- 切换主题等本地偏好也用前缀 key,不得复用无命名空间的 `theme` / `darkMode`。
|
||||
|
||||
### 5.5 事件监听与定时器必须卸载清理
|
||||
|
||||
- 所有 `addEventListener`(`window` / `document` / `rootRef`)、`setTimeout`、`setInterval`、`requestAnimationFrame` 必须在 `useEffect` 的返回函数中 `removeEventListener` / `clearTimeout` / `clearInterval` / `cancelAnimationFrame`。
|
||||
- 模块可被用户随时切走,残留监听器会跨模块执行并导致内存泄漏。
|
||||
|
||||
### 5.6 Portal 挂载点必须在模块根容器内部
|
||||
|
||||
- 弹窗、抽屉、Tooltip 等 `ReactDOM.createPortal(...)` 的第二个参数(容器)**必须**指向模块根容器内部的节点(如 `rootRef.current` 或根容器内的 `<div id="xxx-portal-root">`)。
|
||||
- **禁止**挂到 `document.body`——否则模块卸载后 Portal DOM 残留在 body,样式与交互污染全局。
|
||||
- 若第三方组件默认 portal 到 body,需通过 API 指定 `getContainer` / `appendTo` / `container` 为模块根容器。
|
||||
|
||||
### 5.7 document.title 由平台托管
|
||||
|
||||
- 模块**不得**自行 `document.title = ...`。
|
||||
- 平台 `ModuleTitle` 组件在进入模块时设置标题为模块中文名,卸载时恢复 `'EIOSpace'`(见 §7 平台注册)。
|
||||
|
||||
### 5.8 第三方全局样式/脚本注入禁令
|
||||
|
||||
- 禁止在模块代码中动态 `<script src="...">` 注入第三方 SDK 到 `document.head` / `document.body`(如统计、地图、编辑器);必须用时改为 `import` 打包或挂到模块根容器内。
|
||||
- 禁止 `@import` 全局 reset / normalize(见 §4.4)。
|
||||
|
||||
### 5.9 双门禁(check:styles + check:independence)
|
||||
|
||||
| 门禁 | 命令 | 零容忍范围 |
|
||||
|---|---|---|
|
||||
| 样式门禁 | `npm run check:styles` | CSS 全局选择器(裸标签、`:root`、`*`、`@import` reset 等,见 §4.5) |
|
||||
| 独立门禁 | `npm run check:independence` | 全局 DOM 写入(`document.body` / `documentElement` 的 style/classList)、`document.head` 注入 link/style/script、`document.body` Portal、无前缀 storage key |
|
||||
|
||||
双门禁已接入 build:
|
||||
|
||||
```bash
|
||||
npm run build # = tsc -b && npm run check:styles && npm run check:independence && vite build
|
||||
```
|
||||
|
||||
日常可单独运行:
|
||||
|
||||
```bash
|
||||
npm run check:independence # 退出码 0 = 无全局 DOM / Portal / 无前缀 storage 违规
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 代码适配
|
||||
|
||||
### 6.1 入口与 Provider
|
||||
|
||||
```tsx
|
||||
// App.tsx 末尾:平台路由直接渲染默认导出,Provider 职责从 main.tsx 移到这里
|
||||
@@ -152,13 +222,13 @@ export default function App() {
|
||||
|
||||
同时把源 `main.tsx` 的 CSS import 全部搬到模块 `App.tsx` 顶部(保持原有顺序)。
|
||||
|
||||
### 5.2 严格 tsconfig 适配(tsc -b 报错清单)
|
||||
### 6.2 严格 tsconfig 适配(tsc -b 报错清单)
|
||||
|
||||
- `TS6133` 未使用变量/import → 删除(含解构中未使用的成员)
|
||||
- `TS2554`:`useRef<T>()` → `useRef<T | undefined>(undefined)`(@types/react 19 要求初始值)
|
||||
- 默认导入 `import React` 未使用 → 删除(react-jsx transform 无需)
|
||||
|
||||
### 5.3 其他常见点
|
||||
### 6.3 其他常见点
|
||||
|
||||
- 事件监听/定时器在组件卸载时清理(模块可被随时切走)
|
||||
- 弹窗内 `dangerouslySetInnerHTML` 注入的 HTML,其类名也要被命名空间 CSS 覆盖(确认前缀后仍能匹配)
|
||||
@@ -166,7 +236,7 @@ export default function App() {
|
||||
|
||||
---
|
||||
|
||||
## 6. 平台注册(三件套 + 图标)
|
||||
## 7. 平台注册(三件套 + 图标)
|
||||
|
||||
```ts
|
||||
// 1. src/modules/<name>/index.ts
|
||||
@@ -205,12 +275,13 @@ const XxxApp = lazy(() => import('@/modules/<name>/App'));
|
||||
|
||||
---
|
||||
|
||||
## 7. 验证清单
|
||||
## 8. 验证清单
|
||||
|
||||
**构建层**
|
||||
- [ ] `npx tsc --noEmit` 通过
|
||||
- [ ] `npm run build` 通过(注意 `tsc -b` 比 `tsc --noEmit` 更严,以 build 为准;已含 `check:styles` 门禁)
|
||||
- [ ] `npm run build` 通过(注意 `tsc -b` 比 `tsc --noEmit` 更严,以 build 为准;已含 `check:styles` + `check:independence` 双门禁)
|
||||
- [ ] `npm run check:styles` 退出码 0(模块 CSS 全局选择器零容忍门禁,见 §4.5,已接入 build)
|
||||
- [ ] `npm run check:independence` 退出码 0(全局 DOM 写入 / body Portal / 无前缀 storage key 零容忍门禁,见 §5.9,已接入 build)
|
||||
- [ ] `dist/mod-assets/<name>/` 资源齐全
|
||||
- [ ] **`ls dist/` 确认根目录下没有与模块路由同名的目录**(防端口泄漏,见 §3)
|
||||
|
||||
@@ -226,6 +297,8 @@ sessionStorage.setItem('userInfo', JSON.stringify({ name: '演示用户', userId
|
||||
- [ ] 首页出现新模块卡片(图标、配色正确)
|
||||
- [ ] 首页(未进入任何模块)Network 面板无任何模块级 CSS chunk
|
||||
- [ ] 首次进入模块路由时按需加载对应 JS+CSS chunk(React.lazy 生效)
|
||||
- [ ] **进入模块再返回首页,首页视觉无污染**(body class/style 无残留、CSS 变量无残留、无 Portal 残留 DOM)
|
||||
- [ ] **弹窗/抽屉等 Portal 的 DOM 位于模块根容器内部**(Elements 面板检查,非 `document.body` 直接子节点)
|
||||
|
||||
**回归层(改了旧模块 CSS 时必做)**
|
||||
- [ ] 新模块关键布局 computed style 复核(如 nav 的 display)
|
||||
@@ -234,7 +307,7 @@ sessionStorage.setItem('userInfo', JSON.stringify({ name: '演示用户', userId
|
||||
|
||||
---
|
||||
|
||||
## 8. 部署注意(nginx)
|
||||
## 9. 部署注意(nginx)
|
||||
|
||||
- `nginx.conf` SPA 回退必须是 `try_files $uri /index.html;`——**禁止 `$uri/`**(目录命中 → 403 且不回退)
|
||||
- **必须加两条重定向加固**(防止容器内端口泄漏到浏览器地址栏,2026-10 事故根因):
|
||||
@@ -260,7 +333,7 @@ curl -sI https://ai-workshop.digiwincloud.com.cn/<name> | head -5
|
||||
|
||||
---
|
||||
|
||||
## 9. 历史踩坑速查表
|
||||
## 10. 历史踩坑速查表
|
||||
|
||||
| 案例 | 坑 | 修复 |
|
||||
|---|---|---|
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
# Checklist
|
||||
- [x] jieya-ibp/context/ThemeContext.tsx 不再写 document.documentElement / document.body,CSS 变量与背景/文字色由 ThemeProvider 作用域容器承载
|
||||
- [x] welltrust-qap/context/ThemeContext.tsx 同上改造
|
||||
- [x] order-cost-analysis CostCockpit 移除对 documentElement 的 --body-bg 死变量写入
|
||||
- [x] bomx Drawer 的 createPortal 挂载点位于 .bomx-app 子树内,不再挂 document.body(portalMount 必传,无 document.body 兜底)
|
||||
- [x] 浏览器验证:进入 jieya 后返回首页,首页背景与文字色未被模组主题覆盖(body style 串 before==during==after)
|
||||
- [x] 浏览器验证:jieya 明暗主题切换正常(作用于 .jieya-root);welltrust 同构;bomx Drawer 当前未实例化
|
||||
- [x] scripts/check-module-independence.mjs 存在,能检出全局 DOM 写入、head 注入、body Portal、无前缀 storage key,违规非零退出
|
||||
- [x] package.json 含 check:independence,build 已接入 check:styles + check:independence 双门禁
|
||||
- [x] npm run check:independence 退出码 0
|
||||
- [x] npm run check:styles 退出码 0
|
||||
- [x] npm run build 通过
|
||||
- [x] docs/react-module-integration-sop.md 含「模组完全独立互不影响」完整规则与双门禁说明
|
||||
- [x] .trae/skills/react-module-integration/SKILL.md 与 references 副本同步更新
|
||||
@@ -0,0 +1,58 @@
|
||||
# 模组完全独立互不影响 Spec
|
||||
|
||||
## Why
|
||||
此前已完成「模组 CSS 按需加载 + 选择器命名空间隔离」(spec `isolate-and-lazyload-module-styles`),但跨模组污染不止 CSS 一项。审计发现仍存在模组在运行时直接写入全局 DOM 且卸载不恢复的行为(jieya-ibp / welltrust-qap 的 ThemeContext 把 CSS 变量写到 `document.documentElement`、把 `background`/`color` 写到 `document.body`;order-cost-analysis 的 CostCockpit 向 `documentElement` 写 `--body-bg` 死变量)。这些值在用户离开模组后仍残留在全局,会污染首页与其它模组的视觉。从「每个模组完全独立、互不影响」的角度,需要在 CSS 之外补齐全局 DOM、存储、事件、Portal 等维度的隔离,并把规则沉淀进 SOP 与技能文档。
|
||||
|
||||
## What Changes
|
||||
- **修复全局 DOM 写入污染**:jieya-ibp 与 welltrust-qap 的 `ThemeContext` 不再写 `document.documentElement` / `document.body`,改为由 `ThemeProvider` 渲染的作用域容器承载 CSS 变量与背景/文字色(CSS 变量向下继承,模组内所有 `var(--xxx)` 正常取值);order-cost-analysis CostCockpit 移除向 `documentElement` 写 `--body-bg` 的死代码。
|
||||
- **Portal 挂载规范化**:bomx Drawer 目前用 `createPortal(..., document.body)`(已用 `.bomx-app` 包裹层解决 CSS 作用域);作为最佳实践,将 Portal 内容挂到模块根容器内的 Portal 挂载点,避免全局 body 出现非受控 DOM。
|
||||
- **新增模组独立门禁脚本**:`scripts/check-module-independence.mjs`,扫描 `src/modules/**/*.{ts,tsx,js,jsx}`,检测 `document.body.style`/`document.body.classList`、`document.documentElement.style`/`setAttribute`、`document.head.appendChild`/`insertBefore`(注入 link/style)、`createPortal` 第二参数为 `document.body`、`localStorage`/`sessionStorage` key 不带模组前缀等违规模式,非零退出;接入 `npm run check:independence` 并加入 `build` 门禁。
|
||||
- **文档沉淀**:更新 `docs/react-module-integration-sop.md` 与 `.trae/skills/react-module-integration`(含 references 副本),新增「模组独立不互相影响」章节,覆盖:CSS 选择器命名空间、CSS 变量作用域、全局 DOM 写入禁令、storage key 前缀、事件/定时器卸载清理、Portal 挂载、document.title、第三方全局样式/脚本注入禁令,并给出 check:styles + check:independence 双门禁说明。
|
||||
|
||||
## Impact
|
||||
- Affected specs: `isolate-and-lazyload-module-styles`(CSS 隔离已完成,本 spec 扩展到全维度)
|
||||
- Affected code:
|
||||
- `src/modules/jieya-ibp/context/ThemeContext.tsx`、`src/modules/welltrust-qap/context/ThemeContext.tsx`(全局写入改作用域容器)
|
||||
- `src/modules/order-cost-analysis/pages-orig/CostCockpit.tsx`(移除死变量写入)
|
||||
- `src/modules/bomx-reuse-analyzer/components/Drawer.tsx`(Portal 挂载点内移)
|
||||
- `scripts/check-module-independence.mjs`(新增)
|
||||
- `package.json`(新增 `check:independence`,build 接入)
|
||||
- `docs/react-module-integration-sop.md`、`.trae/skills/react-module-integration/SKILL.md`、`.trae/skills/react-module-integration/references/react-module-integration-sop.md`(文档沉淀)
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 模组不得写入全局 DOM 且卸载后无残留
|
||||
系统 SHALL 保证每个模组在运行期不修改 `document.body` / `document.documentElement` 的 `style`/`classList`,不向 `document.head` 注入 `<link>`/`<style>`/`<script>`;模组的 CSS 变量、背景色、文字色等主题令牌 SHALL 仅作用于模组根容器及其后代。
|
||||
|
||||
#### Scenario: 访问 jieya-ibp 后回到首页
|
||||
- **WHEN** 用户进入 `/jieya-ibp` 再返回首页 `/`
|
||||
- **THEN** 首页背景色与文字色为平台默认值,未被 jieya 的深色主题覆盖
|
||||
|
||||
#### Scenario: 主题令牌仅在模组内生效
|
||||
- **WHEN** jieya-ibp 切换明暗主题
|
||||
- **THEN** `--body-bg`/`--scroll-thumb`/`--glow-color`/`--hover-bg` 等变量仅在 `.jieya-root` 子树内生效,`getComputedStyle(document.documentElement).getPropertyValue('--body-bg')` 不含模组值
|
||||
|
||||
### Requirement: 模组门户(Portal)挂载于模组根容器内
|
||||
系统 SHALL 保证模组的弹窗/抽屉等 Portal 内容挂载在模组根容器内部的 DOM 节点,而非 `document.body`,避免全局 body 出现非模组受控的 DOM。
|
||||
|
||||
#### Scenario: bomx 抽屉挂载点
|
||||
- **WHEN** 打开 bomx-reuse-analyzer 的 Drawer
|
||||
- **THEN** 抽屉 DOM 节点位于 `.bomx-app` 子树内,而非 `document.body` 的直接子节点
|
||||
|
||||
### Requirement: 模组独立自动化门禁
|
||||
系统 SHALL 提供 `npm run check:independence` 脚本,扫描模组代码中的全局 DOM 写入、head 注入、body Portal、无前缀 storage key 等独立违规,作为构建门禁。
|
||||
|
||||
#### Scenario: 门禁通过
|
||||
- **WHEN** 所有模组均无全局 DOM 写入、Portal 均挂在根容器内、storage key 均带模组前缀
|
||||
- **THEN** `npm run check:independence` 退出码 0
|
||||
|
||||
#### Scenario: 门禁发现违规
|
||||
- **WHEN** 某模组存在 `document.body.style.xxx` 或 `createPortal(x, document.body)`
|
||||
- **THEN** 脚本输出违规文件+行号+原因,退出码非 0,`npm run build` 失败
|
||||
|
||||
### Requirement: 模组独立规则文档化
|
||||
SOP 文档与 react-module-integration 技能 SHALL 包含「模组完全独立互不影响」的完整规则清单与双门禁(check:styles + check:independence)说明。
|
||||
|
||||
#### Scenario: 查阅文档
|
||||
- **WHEN** 查阅 SOP 或技能文件
|
||||
- **THEN** 可找到全局 DOM 写入禁令、CSS 变量作用域、storage key 前缀、事件/定时器清理、Portal 挂载、document.title、第三方注入禁令等规则,以及双门禁运行方式
|
||||
@@ -0,0 +1,29 @@
|
||||
# Tasks
|
||||
|
||||
- [x] Task 1: 修复全局 DOM 写入污染(jieya-ibp / welltrust-qap ThemeContext)
|
||||
- [x] SubTask 1.1: `jieya-ibp/context/ThemeContext.tsx`:移除 `useEffect` 中对 `document.documentElement` 的 `setProperty` 与 `document.body.style.background/color`;改为 `ThemeProvider` 返回的 `<ThemeContext.Provider>` 内包裹一层作用域 `<div>`,以 inline style 设置 `--body-bg`/`--scroll-thumb`/`--glow-color`/`--hover-bg` 变量与 `background`/`color`(值取自 `tokens`),宽高 100% 承接 `AppInner` 的 100vw/100vh 根容器
|
||||
- [x] SubTask 1.2: `welltrust-qap/context/ThemeContext.tsx`:同 1.1 改造
|
||||
- [x] SubTask 1.3: `order-cost-analysis/pages-orig/CostCockpit.tsx`:移除向 `document.documentElement` 写 `--body-bg` 的 `useEffect`(`var(--body-bg)` 在模组内无引用,属死代码)
|
||||
- [x] SubTask 1.4: 浏览器验证:进入 jieya 再回首页,首页背景/文字色未被覆盖;jieya 明暗主题切换正常(welltrust 同构改造,tsc + build 通过)
|
||||
- [x] Task 2: Portal 挂载点内移(bomx Drawer)
|
||||
- [x] SubTask 2.1: `bomx-reuse-analyzer/pages/BomxReuseHome.tsx` 根容器内新增 Portal 挂载点 `<div ref={portalMountRef} />`
|
||||
- [x] SubTask 2.2: `bomx-reuse-analyzer/components/Drawer.tsx`:`createPortal` 第二参数改为必传 `portalMount: HTMLDivElement`,彻底移除 `document.body` 兜底
|
||||
- [x] SubTask 2.3: Drawer 当前未被任何文件引用(死代码),无运行时实例;`.bomx-app` 根容器无 transform/filter/perspective,不会破坏 fixed 遮罩
|
||||
- [x] Task 3: 新增模组独立门禁脚本
|
||||
- [x] SubTask 3.1: 新增 `scripts/check-module-independence.mjs`(ESM 零依赖),扫描 `src/modules/**/*.{ts,tsx,js,jsx}`,检测 5 类违规(body 样式写入、documentElement 写入、head 注入、body Portal、无前缀 storage key),跳过字符串与注释,违规非零退出
|
||||
- [x] SubTask 3.2: `package.json` 增加 `check:independence`;`build` 改为 `tsc -b && npm run check:styles && npm run check:independence && vite build`
|
||||
- [x] SubTask 3.3: 自测:修复后退出码 0(扫描 270 文件);故意保留/插入的违规样例可正确检出(已验证 bomx Drawer、knowledge-graph 两处真实违规被检出并修复)
|
||||
- [x] Task 4: 文档沉淀(SOP + 技能)
|
||||
- [x] SubTask 4.1: `docs/react-module-integration-sop.md` 新增 §5「模组完全独立互不影响」(5.1–5.9),覆盖全维度规则与双门禁说明;章节顺延
|
||||
- [x] SubTask 4.2: `.trae/skills/react-module-integration/SKILL.md` 红线与验证清单同步
|
||||
- [x] SubTask 4.3: `.trae/skills/react-module-integration/references/react-module-integration-sop.md` 与 docs 完全同源(diff 无输出)
|
||||
- [x] Task 5: 端到端验证
|
||||
- [x] SubTask 5.1: `npm run build` 通过(含双门禁),dist 无回归
|
||||
- [x] SubTask 5.2: 浏览器验证:首页→jieya→首页 body 样式串 before/during/after 完全一致(仅平台深色主题值),jieya 主题背景作用于 `.jieya-root`;控制台无报错
|
||||
- [x] SubTask 5.3: `npm run check:independence` 与 `npm run check:styles` 均退出码 0
|
||||
|
||||
# Task Dependencies
|
||||
- Task 1、Task 2 互相独立,可并行
|
||||
- Task 3 依赖 Task 1、Task 2(修复后门禁才能通过;门禁脚本本身可先写,用 HEAD 版本验证检出能力)
|
||||
- Task 4 与 Task 1/2/3 无代码冲突,可并行
|
||||
- Task 5 依赖 Task 1-4
|
||||
@@ -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 <div className="xxx-root" ref={rootRef}>...</div>
|
||||
|
||||
### 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` 注入 `<link>`、`<style>`、`<script>` 标签。
|
||||
- 需要锁滚动、切主题等副作用时,一律作用于模块根容器 `ref`,并在卸载时恢复。
|
||||
|
||||
### 5.4 存储 key 必须带模块前缀
|
||||
|
||||
- localStorage / sessionStorage 的 key 必须带模块前缀(如 `wuchuan-quotation-v1`、`sp_theme`、`ocDataSourceMode`、`welltrust-qap-*` 等)。
|
||||
- **白名单**:平台级 `userToken`、`userInfo` 可直接读写,模块不得新增其它无前缀全局 key。
|
||||
- 切换主题等本地偏好也用前缀 key,不得复用无命名空间的 `theme` / `darkMode`。
|
||||
|
||||
### 5.5 事件监听与定时器必须卸载清理
|
||||
|
||||
- 所有 `addEventListener`(`window` / `document` / `rootRef`)、`setTimeout`、`setInterval`、`requestAnimationFrame` 必须在 `useEffect` 的返回函数中 `removeEventListener` / `clearTimeout` / `clearInterval` / `cancelAnimationFrame`。
|
||||
- 模块可被用户随时切走,残留监听器会跨模块执行并导致内存泄漏。
|
||||
|
||||
### 5.6 Portal 挂载点必须在模块根容器内部
|
||||
|
||||
- 弹窗、抽屉、Tooltip 等 `ReactDOM.createPortal(...)` 的第二个参数(容器)**必须**指向模块根容器内部的节点(如 `rootRef.current` 或根容器内的 `<div id="xxx-portal-root">`)。
|
||||
- **禁止**挂到 `document.body`——否则模块卸载后 Portal DOM 残留在 body,样式与交互污染全局。
|
||||
- 若第三方组件默认 portal 到 body,需通过 API 指定 `getContainer` / `appendTo` / `container` 为模块根容器。
|
||||
|
||||
### 5.7 document.title 由平台托管
|
||||
|
||||
- 模块**不得**自行 `document.title = ...`。
|
||||
- 平台 `ModuleTitle` 组件在进入模块时设置标题为模块中文名,卸载时恢复 `'EIOSpace'`(见 §7 平台注册)。
|
||||
|
||||
### 5.8 第三方全局样式/脚本注入禁令
|
||||
|
||||
- 禁止在模块代码中动态 `<script src="...">` 注入第三方 SDK 到 `document.head` / `document.body`(如统计、地图、编辑器);必须用时改为 `import` 打包或挂到模块根容器内。
|
||||
- 禁止 `@import` 全局 reset / normalize(见 §4.4)。
|
||||
|
||||
### 5.9 双门禁(check:styles + check:independence)
|
||||
|
||||
| 门禁 | 命令 | 零容忍范围 |
|
||||
|---|---|---|
|
||||
| 样式门禁 | `npm run check:styles` | CSS 全局选择器(裸标签、`:root`、`*`、`@import` reset 等,见 §4.5) |
|
||||
| 独立门禁 | `npm run check:independence` | 全局 DOM 写入(`document.body` / `documentElement` 的 style/classList)、`document.head` 注入 link/style/script、`document.body` Portal、无前缀 storage key |
|
||||
|
||||
双门禁已接入 build:
|
||||
|
||||
```bash
|
||||
npm run build # = tsc -b && npm run check:styles && npm run check:independence && vite build
|
||||
```
|
||||
|
||||
日常可单独运行:
|
||||
|
||||
```bash
|
||||
npm run check:independence # 退出码 0 = 无全局 DOM / Portal / 无前缀 storage 违规
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 代码适配
|
||||
|
||||
### 6.1 入口与 Provider
|
||||
|
||||
```tsx
|
||||
// App.tsx 末尾:平台路由直接渲染默认导出,Provider 职责从 main.tsx 移到这里
|
||||
@@ -152,13 +222,13 @@ export default function App() {
|
||||
|
||||
同时把源 `main.tsx` 的 CSS import 全部搬到模块 `App.tsx` 顶部(保持原有顺序)。
|
||||
|
||||
### 5.2 严格 tsconfig 适配(tsc -b 报错清单)
|
||||
### 6.2 严格 tsconfig 适配(tsc -b 报错清单)
|
||||
|
||||
- `TS6133` 未使用变量/import → 删除(含解构中未使用的成员)
|
||||
- `TS2554`:`useRef<T>()` → `useRef<T | undefined>(undefined)`(@types/react 19 要求初始值)
|
||||
- 默认导入 `import React` 未使用 → 删除(react-jsx transform 无需)
|
||||
|
||||
### 5.3 其他常见点
|
||||
### 6.3 其他常见点
|
||||
|
||||
- 事件监听/定时器在组件卸载时清理(模块可被随时切走)
|
||||
- 弹窗内 `dangerouslySetInnerHTML` 注入的 HTML,其类名也要被命名空间 CSS 覆盖(确认前缀后仍能匹配)
|
||||
@@ -166,7 +236,7 @@ export default function App() {
|
||||
|
||||
---
|
||||
|
||||
## 6. 平台注册(三件套 + 图标)
|
||||
## 7. 平台注册(三件套 + 图标)
|
||||
|
||||
```ts
|
||||
// 1. src/modules/<name>/index.ts
|
||||
@@ -205,12 +275,13 @@ const XxxApp = lazy(() => import('@/modules/<name>/App'));
|
||||
|
||||
---
|
||||
|
||||
## 7. 验证清单
|
||||
## 8. 验证清单
|
||||
|
||||
**构建层**
|
||||
- [ ] `npx tsc --noEmit` 通过
|
||||
- [ ] `npm run build` 通过(注意 `tsc -b` 比 `tsc --noEmit` 更严,以 build 为准;已含 `check:styles` 门禁)
|
||||
- [ ] `npm run build` 通过(注意 `tsc -b` 比 `tsc --noEmit` 更严,以 build 为准;已含 `check:styles` + `check:independence` 双门禁)
|
||||
- [ ] `npm run check:styles` 退出码 0(模块 CSS 全局选择器零容忍门禁,见 §4.5,已接入 build)
|
||||
- [ ] `npm run check:independence` 退出码 0(全局 DOM 写入 / body Portal / 无前缀 storage key 零容忍门禁,见 §5.9,已接入 build)
|
||||
- [ ] `dist/mod-assets/<name>/` 资源齐全
|
||||
- [ ] **`ls dist/` 确认根目录下没有与模块路由同名的目录**(防端口泄漏,见 §3)
|
||||
|
||||
@@ -226,6 +297,8 @@ sessionStorage.setItem('userInfo', JSON.stringify({ name: '演示用户', userId
|
||||
- [ ] 首页出现新模块卡片(图标、配色正确)
|
||||
- [ ] 首页(未进入任何模块)Network 面板无任何模块级 CSS chunk
|
||||
- [ ] 首次进入模块路由时按需加载对应 JS+CSS chunk(React.lazy 生效)
|
||||
- [ ] **进入模块再返回首页,首页视觉无污染**(body class/style 无残留、CSS 变量无残留、无 Portal 残留 DOM)
|
||||
- [ ] **弹窗/抽屉等 Portal 的 DOM 位于模块根容器内部**(Elements 面板检查,非 `document.body` 直接子节点)
|
||||
|
||||
**回归层(改了旧模块 CSS 时必做)**
|
||||
- [ ] 新模块关键布局 computed style 复核(如 nav 的 display)
|
||||
@@ -234,7 +307,7 @@ sessionStorage.setItem('userInfo', JSON.stringify({ name: '演示用户', userId
|
||||
|
||||
---
|
||||
|
||||
## 8. 部署注意(nginx)
|
||||
## 9. 部署注意(nginx)
|
||||
|
||||
- `nginx.conf` SPA 回退必须是 `try_files $uri /index.html;`——**禁止 `$uri/`**(目录命中 → 403 且不回退)
|
||||
- **必须加两条重定向加固**(防止容器内端口泄漏到浏览器地址栏,2026-10 事故根因):
|
||||
@@ -260,7 +333,7 @@ curl -sI https://ai-workshop.digiwincloud.com.cn/<name> | head -5
|
||||
|
||||
---
|
||||
|
||||
## 9. 历史踩坑速查表
|
||||
## 10. 历史踩坑速查表
|
||||
|
||||
| 案例 | 坑 | 修复 |
|
||||
|---|---|---|
|
||||
|
||||
+3
-2
@@ -5,9 +5,10 @@
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "vite",
|
||||
"build": "tsc -b && npm run check:styles && vite build",
|
||||
"build": "tsc -b && npm run check:styles && npm run check:independence && vite build",
|
||||
"preview": "vite preview",
|
||||
"check:styles": "node scripts/check-module-styles.mjs"
|
||||
"check:styles": "node scripts/check-module-styles.mjs",
|
||||
"check:independence": "node scripts/check-module-independence.mjs"
|
||||
},
|
||||
"dependencies": {
|
||||
"@ant-design/icons": "^5.4.0",
|
||||
|
||||
@@ -0,0 +1,349 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* 模组独立性检查(门禁脚本)
|
||||
*
|
||||
* 平台规则:src/modules 下每个模组必须完全独立、互不影响,禁止运行时写入全局 DOM、
|
||||
* 向 head 注入全局样式/脚本、将 Portal 挂到 document.body、使用无前缀的 storage key。
|
||||
*
|
||||
* 实现:先做词法剥离(注释 + 字符串/模板字面量),再用正则检测违规模式。
|
||||
* 零依赖,Node >= 18。
|
||||
*/
|
||||
import { readdirSync, readFileSync } from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
||||
const MODULES_DIR = path.join(ROOT, 'src', 'modules');
|
||||
const EXTS = new Set(['.ts', '.tsx', '.js', '.jsx']);
|
||||
|
||||
// 平台级共享 storage key 白名单(不计模组前缀)
|
||||
const STORAGE_WHITELIST = new Set(['userToken', 'userInfo']);
|
||||
|
||||
/* ---------------------------------- 文件收集 ---------------------------------- */
|
||||
|
||||
function collectFiles(dir, out = []) {
|
||||
let entries;
|
||||
try {
|
||||
entries = readdirSync(dir, { withFileTypes: true });
|
||||
} catch {
|
||||
return out;
|
||||
}
|
||||
for (const entry of entries) {
|
||||
const full = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) {
|
||||
collectFiles(full, out);
|
||||
} else if (entry.isFile() && EXTS.has(path.extname(entry.name))) {
|
||||
out.push(full);
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/* -------------------------------- 词法剥离 -------------------------------- */
|
||||
|
||||
/**
|
||||
* 剥离源码中的注释与字符串/模板字面量,保留换行以维持行号对齐。
|
||||
* 返回两份结果:
|
||||
* - commentStripped:仅去掉 // 与 /* *\/ 注释,字符串内容保留(用于需要读取
|
||||
* 字符串字面量的检查,如 storage key、createElement 标签名)。
|
||||
* - fullyStripped:注释 + 字符串/模板全部替换为空格(用于避免字符串内关键字误报)。
|
||||
*
|
||||
* 被剥离的非换行字符统一替换为空格,保证字符偏移与行号不变。
|
||||
*/
|
||||
function stripSource(source) {
|
||||
let commentStripped = '';
|
||||
let fullyStripped = '';
|
||||
let inBlockComment = false;
|
||||
let inTemplate = false;
|
||||
let i = 0;
|
||||
|
||||
const pushSpace = (ch) => {
|
||||
const sp = ch === '\n' ? '\n' : ' ';
|
||||
commentStripped += sp;
|
||||
fullyStripped += sp;
|
||||
};
|
||||
|
||||
while (i < source.length) {
|
||||
const ch = source[i];
|
||||
const next = source[i + 1];
|
||||
|
||||
if (inBlockComment) {
|
||||
if (ch === '*' && next === '/') {
|
||||
inBlockComment = false;
|
||||
commentStripped += ' ';
|
||||
fullyStripped += ' ';
|
||||
i += 2;
|
||||
} else {
|
||||
pushSpace(ch);
|
||||
i++;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
if (inTemplate) {
|
||||
if (ch === '\\') {
|
||||
// 转义字符整体跳过
|
||||
commentStripped += ch + (next || '');
|
||||
fullyStripped += ' ' + (next === '\n' ? '\n' : ' ');
|
||||
i += 2;
|
||||
continue;
|
||||
}
|
||||
if (ch === '`') {
|
||||
inTemplate = false;
|
||||
pushSpace(ch);
|
||||
i++;
|
||||
continue;
|
||||
}
|
||||
if (ch === '$' && next === '{') {
|
||||
// 模板插值:按大括号深度跳过(插值内代码也一并剥离)
|
||||
let depth = 1;
|
||||
commentStripped += ' ';
|
||||
fullyStripped += ' ';
|
||||
i += 2;
|
||||
while (i < source.length && depth > 0) {
|
||||
const c = source[i];
|
||||
if (c === '{') depth++;
|
||||
else if (c === '}') depth--;
|
||||
pushSpace(c);
|
||||
i++;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
pushSpace(ch);
|
||||
i++;
|
||||
continue;
|
||||
}
|
||||
|
||||
// —— 普通代码态 ——
|
||||
if (ch === '/' && next === '/') {
|
||||
// 行注释:跳到行尾
|
||||
while (i < source.length && source[i] !== '\n') {
|
||||
commentStripped += ' ';
|
||||
fullyStripped += ' ';
|
||||
i++;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (ch === '/' && next === '*') {
|
||||
inBlockComment = true;
|
||||
commentStripped += ' ';
|
||||
fullyStripped += ' ';
|
||||
i += 2;
|
||||
continue;
|
||||
}
|
||||
if (ch === '`') {
|
||||
inTemplate = true;
|
||||
pushSpace(ch);
|
||||
i++;
|
||||
continue;
|
||||
}
|
||||
if (ch === '"' || ch === "'") {
|
||||
const quote = ch;
|
||||
commentStripped += ch; // commentStripped 保留字符串内容
|
||||
fullyStripped += ' ';
|
||||
i++;
|
||||
while (i < source.length) {
|
||||
const c = source[i];
|
||||
if (c === '\\') {
|
||||
commentStripped += c + (source[i + 1] || '');
|
||||
fullyStripped += ' ' + (source[i + 1] === '\n' ? '\n' : ' ');
|
||||
i += 2;
|
||||
continue;
|
||||
}
|
||||
if (c === quote) {
|
||||
commentStripped += quote;
|
||||
fullyStripped += ' ';
|
||||
i++;
|
||||
break;
|
||||
}
|
||||
if (c === '\n') {
|
||||
// 字符串跨行(非法 JS,但容错)
|
||||
commentStripped += '\n';
|
||||
fullyStripped += '\n';
|
||||
i++;
|
||||
continue;
|
||||
}
|
||||
commentStripped += c;
|
||||
fullyStripped += ' ';
|
||||
i++;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
commentStripped += ch;
|
||||
fullyStripped += ch;
|
||||
i++;
|
||||
}
|
||||
|
||||
return { commentStripped, fullyStripped };
|
||||
}
|
||||
|
||||
/* ------------------------------ 工具:顶层逗号切分 ------------------------------ */
|
||||
|
||||
/** 按顶层逗号切分参数列表,括号/方括号/花括号内的逗号不切分。 */
|
||||
function splitTopLevel(s) {
|
||||
const parts = [];
|
||||
let cur = '';
|
||||
let paren = 0, bracket = 0, brace = 0;
|
||||
for (const ch of s) {
|
||||
if (ch === '(') paren++;
|
||||
else if (ch === ')') paren--;
|
||||
else if (ch === '[') bracket++;
|
||||
else if (ch === ']') bracket--;
|
||||
else if (ch === '{') brace++;
|
||||
else if (ch === '}') brace--;
|
||||
if (ch === ',' && paren === 0 && bracket === 0 && brace === 0) {
|
||||
parts.push(cur);
|
||||
cur = '';
|
||||
continue;
|
||||
}
|
||||
cur += ch;
|
||||
}
|
||||
parts.push(cur);
|
||||
return parts;
|
||||
}
|
||||
|
||||
/** 计算字符串中 index 位置对应的行号(1-based)。 */
|
||||
function lineAt(text, index) {
|
||||
let line = 1;
|
||||
for (let k = 0; k < index && k < text.length; k++) {
|
||||
if (text[k] === '\n') line++;
|
||||
}
|
||||
return line;
|
||||
}
|
||||
|
||||
/* -------------------------------- 违规判定 -------------------------------- */
|
||||
|
||||
/**
|
||||
* 判定 storage key 是否合规:
|
||||
* - 在白名单内;或
|
||||
* - 包含 - / _ / . ;或
|
||||
* - 匹配小写驼峰模块前缀 ^[a-z]{2,}[A-Z](如 ocDataSourceMode)。
|
||||
*/
|
||||
function isStorageKeyCompliant(key) {
|
||||
if (STORAGE_WHITELIST.has(key)) return true;
|
||||
if (/[-_.]/.test(key)) return true;
|
||||
if (/^[a-z]{2,}[A-Z]/.test(key)) return true;
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* 扫描单个文件,返回违规列表 [{ line, reason }]。
|
||||
*/
|
||||
function scanFile(source) {
|
||||
const violations = [];
|
||||
const { commentStripped, fullyStripped } = stripSource(source);
|
||||
|
||||
const commentLines = commentStripped.split('\n');
|
||||
const fullyLines = fullyStripped.split('\n');
|
||||
|
||||
// —— 预扫描:收集被赋值为 createElement('link'|'style'|'script') 的变量名 ——
|
||||
// 用于跨行判定 document.head.appendChild(var) 是否为注入全局样式/脚本。
|
||||
const injectVars = new Set();
|
||||
const assignRe = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*document\.createElement\s*\(\s*['"`](link|style|script)['"`]/g;
|
||||
for (const line of commentLines) {
|
||||
let m;
|
||||
while ((m = assignRe.exec(line)) !== null) {
|
||||
injectVars.add(m[1]);
|
||||
}
|
||||
}
|
||||
|
||||
// —— 逐行检测(a / b / c / e)——
|
||||
for (let idx = 0; idx < fullyLines.length; idx++) {
|
||||
const lineNo = idx + 1;
|
||||
const fLine = fullyLines[idx];
|
||||
const cLine = commentLines[idx];
|
||||
|
||||
// a. document.body.(style|classList).
|
||||
if (/document\.body\.(style|classList)\./.test(fLine)) {
|
||||
violations.push({ line: lineNo, reason: '写入 document.body 的 style/classList(应仅作用于模组根容器)' });
|
||||
}
|
||||
|
||||
// b. document.documentElement.(style|setAttribute|classList).
|
||||
if (/document\.documentElement\.(style|setAttribute|classList)\./.test(fLine)) {
|
||||
violations.push({ line: lineNo, reason: '写入 document.documentElement 的 style/setAttribute/classList(CSS 变量应挂在模组根容器)' });
|
||||
}
|
||||
|
||||
// c. document.head.appendChild/insertBefore 注入 link/style/script
|
||||
if (/document\.head\.(appendChild|insertBefore)\s*\(/.test(cLine)) {
|
||||
// 同行内是否直接 createElement('link'|'style'|'script')
|
||||
const inlineInject = /createElement\s*\(\s*['"`](link|style|script)['"`]/.test(cLine);
|
||||
// 或参数为前面收集到的注入变量
|
||||
let varInject = false;
|
||||
if (!inlineInject) {
|
||||
const argMatch = cLine.match(/document\.head\.(?:appendChild|insertBefore)\s*\(\s*([A-Za-z_$][\w$]*)/);
|
||||
if (argMatch && injectVars.has(argMatch[1])) varInject = true;
|
||||
}
|
||||
if (inlineInject || varInject) {
|
||||
violations.push({ line: lineNo, reason: '向 document.head 注入 link/style/script 元素(禁止模组注入全局样式/脚本)' });
|
||||
}
|
||||
}
|
||||
|
||||
// e. localStorage/sessionStorage key 无前缀
|
||||
const storageRe = /(local|session)Storage\.(getItem|setItem|removeItem)\s*\(\s*['"`]([^'"`]+)['"`]/g;
|
||||
let sm;
|
||||
while ((sm = storageRe.exec(cLine)) !== null) {
|
||||
const key = sm[3];
|
||||
if (!isStorageKeyCompliant(key)) {
|
||||
violations.push({ line: lineNo, reason: `storage key「${key}」未带模组前缀(需含 -/_/. 或以小写驼峰模块名开头)` });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// —— 整段检测(d. createPortal 第二参数为 document.body,可能跨多行)——
|
||||
const portalRe = /createPortal\s*\(/g;
|
||||
let pm;
|
||||
while ((pm = portalRe.exec(fullyStripped)) !== null) {
|
||||
const start = pm.index;
|
||||
let depth = 1;
|
||||
let j = start + pm[0].length;
|
||||
while (j < fullyStripped.length && depth > 0) {
|
||||
const c = fullyStripped[j];
|
||||
if (c === '(') depth++;
|
||||
else if (c === ')') depth--;
|
||||
j++;
|
||||
}
|
||||
if (depth === 0) {
|
||||
const args = fullyStripped.slice(start + pm[0].length, j - 1);
|
||||
const parts = splitTopLevel(args);
|
||||
// 第二参数为 Portal 挂载容器:若其中出现 document.body(含兜底表达式
|
||||
// 如 portalMount ?? document.body),即视为挂到全局 body,判违规。
|
||||
if (parts.length >= 2 && /\bdocument\.body\b/.test(parts[1])) {
|
||||
const lineNo = lineAt(fullyStripped, start);
|
||||
violations.push({ line: lineNo, reason: 'createPortal 挂载点含 document.body(Portal 应挂在模组根容器内,禁止兜底到全局 body)' });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return violations;
|
||||
}
|
||||
|
||||
/* ------------------------------------ 主流程 ----------------------------------- */
|
||||
|
||||
function main() {
|
||||
const files = collectFiles(MODULES_DIR).sort();
|
||||
const violations = [];
|
||||
|
||||
for (const file of files) {
|
||||
const rel = path.relative(ROOT, file).split(path.sep).join('/');
|
||||
const source = readFileSync(file, 'utf8');
|
||||
const fileViolations = scanFile(source);
|
||||
for (const v of fileViolations) {
|
||||
violations.push(`[违规] ${rel}:${v.line} ${v.reason}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (violations.length > 0) {
|
||||
for (const v of violations) console.log(v);
|
||||
const badFiles = new Set(violations.map((v) => v.split(':')[0].replace('[违规] ', ''))).size;
|
||||
console.log(
|
||||
`[汇总] 模组独立检查失败:共 ${violations.length} 条违规,涉及 ${badFiles} 个文件(共扫描 ${files.length} 个文件)`,
|
||||
);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log(`✓ 模组独立检查通过(扫描 ${files.length} 个文件)`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
main();
|
||||
@@ -2,8 +2,13 @@ import { useEffect } from 'react';
|
||||
import { createPortal } from 'react-dom';
|
||||
import { IconX } from './Icons';
|
||||
|
||||
// 使用 Portal 渲染到 body,避免被父级层叠上下文/导航条遮挡
|
||||
export default function Drawer({ open, title, onClose, children, width = 540 }: any) {
|
||||
// Portal 渲染到模块根容器内的挂载点(必传 portalMount),
|
||||
// 保持 DOM 节点位于模块作用域内,禁止挂到 document.body
|
||||
export default function Drawer({ open, title, onClose, children, width = 540, portalMount }: {
|
||||
open: boolean; title?: React.ReactNode; onClose: () => void;
|
||||
children?: React.ReactNode; width?: number;
|
||||
portalMount: HTMLDivElement;
|
||||
}) {
|
||||
useEffect(() => {
|
||||
if (!open) return;
|
||||
const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') onClose(); };
|
||||
@@ -32,6 +37,6 @@ export default function Drawer({ open, title, onClose, children, width = 540 }:
|
||||
<div className="drawer-content">{children}</div>
|
||||
</div>
|
||||
</div>,
|
||||
document.body
|
||||
portalMount
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { useEffect, useState, useCallback } from 'react';
|
||||
import { useEffect, useState, useCallback, useRef } from 'react';
|
||||
import { useNavigate } from 'react-router-dom';
|
||||
import { initStore } from '../core/store';
|
||||
import BomBrowser from '../components/BomBrowser';
|
||||
@@ -47,6 +47,9 @@ export default function BomxReuseHome() {
|
||||
const [loadError, setLoadError] = useState<any>(null);
|
||||
const [fadingOut, setFadingOut] = useState(false);
|
||||
|
||||
// Drawer Portal 挂载点:位于 .bomx-app 根容器内部,使 Drawer DOM 节点留在模块作用域内
|
||||
const portalMountRef = useRef<HTMLDivElement>(null);
|
||||
|
||||
const loadData = useCallback(async (sourceKey: string) => {
|
||||
setLoading(true);
|
||||
setFadingOut(false);
|
||||
@@ -164,6 +167,9 @@ export default function BomxReuseHome() {
|
||||
</div>
|
||||
<ToastContainer />
|
||||
|
||||
{/* Drawer Portal 挂载点:Drawer 通过 createPortal 将内容渲染到此节点内 */}
|
||||
<div ref={portalMountRef} />
|
||||
|
||||
{data && (
|
||||
<div className="data-source-switch">
|
||||
<select
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
import { createContext, useContext, useState, useEffect, useCallback } from 'react';
|
||||
import type { ReactNode } from 'react';
|
||||
import { createContext, useContext, useState, useCallback } from 'react';
|
||||
import type { ReactNode, CSSProperties } from 'react';
|
||||
|
||||
export type Theme = 'dark' | 'light';
|
||||
|
||||
@@ -185,19 +185,20 @@ export function ThemeProvider({ children }: { children: ReactNode }) {
|
||||
});
|
||||
}, []);
|
||||
|
||||
useEffect(() => {
|
||||
const root = document.documentElement;
|
||||
root.style.setProperty('--body-bg', tokens.bodyBg);
|
||||
root.style.setProperty('--scroll-thumb', tokens.scrollThumb);
|
||||
root.style.setProperty('--glow-color', tokens.accentGlow);
|
||||
root.style.setProperty('--hover-bg', tokens.tableRowHover);
|
||||
document.body.style.background = tokens.bodyBgImage;
|
||||
document.body.style.color = tokens.text;
|
||||
}, [tokens]);
|
||||
|
||||
return (
|
||||
<ThemeContext.Provider value={{ theme, tokens, toggleTheme }}>
|
||||
<div style={{
|
||||
'--body-bg': tokens.bodyBg,
|
||||
'--scroll-thumb': tokens.scrollThumb,
|
||||
'--glow-color': tokens.accentGlow,
|
||||
'--hover-bg': tokens.tableRowHover,
|
||||
background: tokens.bodyBgImage,
|
||||
color: tokens.text,
|
||||
width: '100%',
|
||||
minHeight: '100vh',
|
||||
} as CSSProperties}>
|
||||
{children}
|
||||
</div>
|
||||
</ThemeContext.Provider>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -32,6 +32,7 @@ export default function KnowledgeGraphHome() {
|
||||
const [sideTab, setSideTab] = useState<SideTab>('stats');
|
||||
const [sidebarWidth, setSidebarWidth] = useState(320);
|
||||
const isDragging = useRef(false);
|
||||
const rootRef = useRef<HTMLDivElement>(null);
|
||||
|
||||
const handleNodeSelect = (node: SelectedNode | null) => setSelectedNode(node);
|
||||
const handleMaterialSelect = (mat: Material | null) => {
|
||||
@@ -46,8 +47,8 @@ export default function KnowledgeGraphHome() {
|
||||
isDragging.current = true;
|
||||
const startX = e.clientX;
|
||||
const startWidth = sidebarWidth;
|
||||
document.body.style.cursor = 'col-resize';
|
||||
document.body.style.userSelect = 'none';
|
||||
rootRef.current?.style.setProperty('cursor', 'col-resize');
|
||||
rootRef.current?.style.setProperty('userSelect', 'none');
|
||||
|
||||
const onMouseMove = (ev: MouseEvent) => {
|
||||
if (!isDragging.current) return;
|
||||
@@ -57,8 +58,8 @@ export default function KnowledgeGraphHome() {
|
||||
};
|
||||
const onMouseUp = () => {
|
||||
isDragging.current = false;
|
||||
document.body.style.cursor = '';
|
||||
document.body.style.userSelect = '';
|
||||
rootRef.current?.style.setProperty('cursor', '');
|
||||
rootRef.current?.style.setProperty('userSelect', '');
|
||||
document.removeEventListener('mousemove', onMouseMove);
|
||||
document.removeEventListener('mouseup', onMouseUp);
|
||||
};
|
||||
@@ -69,7 +70,7 @@ export default function KnowledgeGraphHome() {
|
||||
const viewLabels: Record<ViewMode, string> = { category: '按分类', project: '按项目', aging: '按账龄' };
|
||||
|
||||
return (
|
||||
<div className="flex h-screen w-screen overflow-hidden" style={{ backgroundColor:'#f5f5f7' }}>
|
||||
<div ref={rootRef} className="flex h-screen w-screen overflow-hidden" style={{ backgroundColor:'#f5f5f7' }}>
|
||||
{/* Sidebar */}
|
||||
<aside className="flex-shrink-0 flex flex-col sidebar-bg" style={{ width:sidebarWidth, borderRight:'none' }}>
|
||||
{/* Logo header */}
|
||||
|
||||
@@ -24,11 +24,6 @@ export default function CostCockpit() {
|
||||
const { theme, tokens, toggleTheme } = useTheme();
|
||||
const { orders } = useOrders();
|
||||
|
||||
// 同步 body 背景色(CSS 变量)
|
||||
useEffect(() => {
|
||||
document.documentElement.style.setProperty('--body-bg', tokens.bodyBg);
|
||||
}, [tokens.bodyBg]);
|
||||
|
||||
const [selectedOrder, setSelectedOrder] = useState<Order | null>(null);
|
||||
const [leftExpanded, setLeftExpanded] = useState(false);
|
||||
const [rightExpanded, setRightExpanded] = useState(false);
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
import { createContext, useContext, useState, useEffect, useCallback } from 'react';
|
||||
import type { ReactNode } from 'react';
|
||||
import { createContext, useContext, useState, useCallback } from 'react';
|
||||
import type { ReactNode, CSSProperties } from 'react';
|
||||
|
||||
export type Theme = 'dark' | 'light';
|
||||
|
||||
@@ -193,19 +193,20 @@ export function ThemeProvider({ children }: { children: ReactNode }) {
|
||||
});
|
||||
}, []);
|
||||
|
||||
useEffect(() => {
|
||||
const root = document.documentElement;
|
||||
root.style.setProperty('--body-bg', tokens.bodyBg);
|
||||
root.style.setProperty('--scroll-thumb', tokens.scrollThumb);
|
||||
root.style.setProperty('--glow-color', tokens.accentGlow);
|
||||
root.style.setProperty('--hover-bg', tokens.tableRowHover);
|
||||
document.body.style.background = tokens.bodyBgImage;
|
||||
document.body.style.color = tokens.text;
|
||||
}, [tokens]);
|
||||
|
||||
return (
|
||||
<ThemeContext.Provider value={{ theme, tokens, toggleTheme }}>
|
||||
<div style={{
|
||||
'--body-bg': tokens.bodyBg,
|
||||
'--scroll-thumb': tokens.scrollThumb,
|
||||
'--glow-color': tokens.accentGlow,
|
||||
'--hover-bg': tokens.tableRowHover,
|
||||
background: tokens.bodyBgImage,
|
||||
color: tokens.text,
|
||||
width: '100%',
|
||||
minHeight: '100vh',
|
||||
} as CSSProperties}>
|
||||
{children}
|
||||
</div>
|
||||
</ThemeContext.Provider>
|
||||
);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user