update css

This commit is contained in:
dongsk
2026-10-18 23:02:15 +08:00
parent 90ee2b30f5
commit 9c45aedbe8
19 changed files with 480 additions and 131 deletions
@@ -7,7 +7,7 @@
## 0. 核心原则(先记住这四条)
1. **样式绝对隔离**:平台所有模块的 CSS 会同时全局加载(静态 import,无懒加载隔离),任何裸元素选择器、`:root`/`body` 全局规则、裸 class/ID 选择器都会跨模块污染。**模块所有 CSS 选择器必须挂在模块根容器类下**。
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/<模块名>/`。
3. **零平台侵入**:模块不得修改 `document.body`/`document.documentElement` 的 class/style,不得占用全局 localStorage key,不得与平台路由冲突。
4. **入口职责迁移**:源项目 `main.tsx` 中的 Provider 包裹、全局 CSS 引入等职责,全部迁移到模块 `App.tsx`,平台路由直接渲染模块默认导出。
@@ -123,6 +123,14 @@ return <div className="xxx-root" ref={rootRef}>...</div>
- `@keyframes` 命名全平台唯一(冲突时给新模块 keyframes 加前缀)
- 各模块 CSS 文件内不放 `@import` 全局重置(normalize/reset 一律禁止)
### 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`),日常可单独运行:
```bash
npm run check:styles # 退出码 0 = 模块 CSS 无全局选择器违规
```
---
## 5. 代码适配
@@ -180,11 +188,19 @@ export const moduleConfig: ModuleConfig = {
```ts
// 2. src/modules/registry.ts:import + modules 数组追加
// 3. src/App.tsx:路由(ModuleTitle 负责页签标题,卸载恢复 'EIOSpace')
<Route path="/<name>" element={<RequireAuth><ModuleTitle title="模块中文名"><XxxApp /></ModuleTitle></RequireAuth>} />
// 3. src/App.tsx:模块级 React.lazy 动态导入 + 路由(ModuleTitle 负责页签标题,卸载恢复 'EIOSpace')
const XxxApp = lazy(() => import('@/modules/<name>/App'));
...
<Routes>
<Suspense fallback={<ModuleLoading />}>
<Route path="/<name>" element={<RequireAuth><ModuleTitle title="模块中文名"><XxxApp /></ModuleTitle></RequireAuth>} />
...
</Suspense>
</Routes>
// 4. src/pages/HomePage.tsx:ICON_MAP 增加图标(先在 lucide-react import 中补图标名)
```
> 模块入口必须用 `React.lazy` 动态导入(模块 CSS 随路由 chunk 按需加载),**静态 import 会把模块 CSS 打进主包,禁止**。
> 首页卡片点击已是 `window.open(mod.path, '_blank')` 新页签打开,无需额外处理。
---
@@ -193,7 +209,8 @@ export const moduleConfig: ModuleConfig = {
**构建层**
- [ ] `npx tsc --noEmit` 通过
- [ ] `npm run build` 通过(注意 `tsc -b` 比 `tsc --noEmit` 更严,以 build 为准)
- [ ] `npm run build` 通过(注意 `tsc -b` 比 `tsc --noEmit` 更严,以 build 为准;已含 `check:styles` 门禁)
- [ ] `npm run check:styles` 退出码 0(模块 CSS 全局选择器零容忍门禁,见 §4.5,已接入 build)
- [ ] `dist/mod-assets/<name>/` 资源齐全
- [ ] **`ls dist/` 确认根目录下没有与模块路由同名的目录**(防端口泄漏,见 §3)
@@ -207,6 +224,8 @@ sessionStorage.setItem('userInfo', JSON.stringify({ name: '演示用户', userId
- [ ] 页内交互可用(菜单切换、弹窗、主题切换)
- [ ] 新页签打开后浏览器标题为模块中文名
- [ ] 首页出现新模块卡片(图标、配色正确)
- [ ] 首页(未进入任何模块)Network 面板无任何模块级 CSS chunk
- [ ] 首次进入模块路由时按需加载对应 JS+CSS chunk(React.lazy 生效)
**回归层(改了旧模块 CSS 时必做)**
- [ ] 新模块关键布局 computed style 复核(如 nav 的 display)
@@ -254,3 +273,4 @@ curl -sI https://ai-workshop.digiwincloud.com.cn/<name> | head -5
| 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>/...'` |
| 全部模块 | 模块 CSS 全局选择器(`:root`/`button`/`table`/`::-webkit-scrollbar`/`*`)跨模块污染 | 加模块根容器前缀 + `check:styles` 门禁(§4.5,已接入 build) |