@nebula-skills/nebula-code-standards 0.1.0

package/skill/microapp-guide.md

@@ -0,0 +1,510 @@
+# 独立仓库微前端子应用接入指南
+
+> 业务前端要不要作为独立仓库？怎么接入 nebula-web 主应用？本文给标准答案，**规则自闭环**，不依赖任何具体业务样板项目。
+
+主应用：`nebula-web/apps/nebula-web-main`（端口 `:3000`）。
+
+---
+
+## 一、两种子应用形态对比
+
+| 维度 | monorepo 内置 | 独立仓库（推荐业务域） |
+|------|-------------|--------------------|
+| 位置 | `nebula-web/apps/nebula-web-{domain}` | 独立 Git 仓库 `nebula-{domain}-web` |
+| `@nebula-web/*` 来源 | `workspace:*`（monorepo 软链） | `latest`（GitLab Package Registry） |
+| 部署管道 | 主应用统一 build | 自带 `deploy/build-deploy.sh` |
+| 适用场景 | 平台公共域（auth / system） | 业务域 |
+| 修改 `@nebula-web/*` | 直接改源码即时生效 | 需在 nebula-web 改源码 → CI 发布 → `pnpm update @nebula-web/*` |
+| 多团队协作 | 单仓库，统一 PR 流程 | 各业务团队独立仓库，权限隔离 |
+
+> 业务子应用 **默认走独立仓库形态**。仅平台公共能力（与认证 / 系统配置绑定的）放进 monorepo。
+
+---
+
+## 二、独立仓库子应用必备文件清单
+
+按本清单创建文件，缺一个都可能导致接入失败。
+
+```
+nebula-{domain}-web/
+├── package.json                # private:true, name=nebula-{domain}-web, scripts: dev/dev:remote/build/typecheck
+├── pnpm-lock.yaml
+├── vite.config.ts              # base/双入口/iceStarkHtmlFixPlugin/proxy
+├── tsconfig.json
+├── index.html                  # <div id="app"></div> + <script src="/src/main.ts">
+├── .env.development            # 本地内网 IP 后端
+├── .env.remote                 # 联调线上域名后端
+├── .env.production             # 生产 API_BASE
+├── .npmrc                      # GitLab Package Registry + auth token
+├── .gitignore                  # 见 [[init-new-project]] §六-.gitignore
+├── deploy/
+│   ├── build-deploy.sh         # macOS/Linux
+│   ├── build-deploy.bat        # Windows CMD
+│   └── build-deploy.ps1        # Windows PowerShell
+├── README.md
+└── src/
+    ├── main.ts                  # setLibraryName + mount/unmount + isInIcestark
+    ├── App.vue                  # 仅 RouterView
+    ├── api/index.ts             # createRequest('/nebula-{domain}')
+    ├── router/routes.ts         # 路由（不含 /{domain}app 前缀，由 getBasename 注入）
+    ├── pages/
+    ├── stores/
+    └── styles/
+```
+
+---
+
+## 三、关键配置详解
+
+### 3.1 package.json
+
+```json
+{
+  "name": "nebula-{domain}-web",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --mode development --host 0.0.0.0 --port {PORT}",
+    "dev:remote": "vite --mode remote --host 0.0.0.0 --port {PORT}",
+    "build": "vite build",
+    "typecheck": "vue-tsc --noEmit",
+    "update:nebula": "pnpm update @nebula-web/components @nebula-web/types @nebula-web/utils"
+  },
+  "dependencies": {
+    "@ice/stark-app": "^1.5.0",
+    "@ice/stark-data": "^0.1.3",
+    "@nebula-web/components": "latest",
+    "@nebula-web/types": "latest",
+    "@nebula-web/utils": "latest",
+    "axios": "^1.7.0",
+    "element-plus": "^2.8.0",
+    "pinia": "^2.2.0",
+    "vue": "^3.5.0",
+    "vue-router": "^4.4.0"
+  }
+}
+```
+
+关键约束：
+- ✅ `"private": true` 防止意外发布
+- ✅ `"name": "nebula-{domain}-web"`（kebab-case 全小写）
+- ✅ 端口必须避开 `3000` / 已被占用的子应用端口（参考主应用 `.env.development`）
+
+### 3.2 vite.config.ts 三大要素
+
+```typescript
+import { fileURLToPath, URL } from 'node:url'
+import { defineConfig, loadEnv } from 'vite'
+import { resolve } from 'path'
+import { readFileSync, writeFileSync } from 'fs'
+import vue from '@vitejs/plugin-vue'
+import AutoImport from 'unplugin-auto-import/vite'
+import Components from 'unplugin-vue-components/vite'
+import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
+import compression from 'vite-plugin-compression'
+import type { Plugin } from 'vite'
+
+/**
+ * 修复 IceStark loadScriptMode:'import' 时 HTML 引用错误 facade 的问题。
+ * 同时把 index.html 和 src/main.ts 作为 Rollup 入口时，
+ *   - index-xxx.js：HTML 用的 facade（无 mount/unmount 导出）
+ *   - main-xxx.js ：main.ts 用的 facade（有 export { mount, unmount }）
+ * 默认 HTML 注入 index-xxx.js，IceStark import() 该文件拿不到导出 → 白屏。
+ * 此插件在 writeBundle 阶段把 HTML 里的 index facade 替换为 main facade。
+ */
+function iceStarkHtmlFixPlugin(): Plugin {
+  return {
+    name: 'icestark-html-fix',
+    apply: 'build',
+    writeBundle(options, bundle) {
+      let indexFacade: string | null = null
+      let mainFacade: string | null = null
+      for (const chunk of Object.values(bundle)) {
+        if (chunk.type === 'chunk' && chunk.isEntry) {
+          if (chunk.name === 'index') indexFacade = chunk.fileName
+          if (chunk.name === 'main') mainFacade = chunk.fileName
+        }
+      }
+      if (!indexFacade || !mainFacade) return
+      const outDir = options.dir ?? 'dist'
+      const htmlPath = resolve(outDir, 'index.html')
+      try {
+        let html = readFileSync(htmlPath, 'utf-8')
+        html = html.replace(indexFacade, mainFacade)
+        writeFileSync(htmlPath, html)
+        console.log(`[icestark-html-fix] ${indexFacade} → ${mainFacade}`)
+      } catch (_e) { /* ignore */ }
+    },
+  }
+}
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), '')
+  const isProd = mode === 'production'
+  const needRewrite = env.VITE_PROXY_REWRITE !== 'false'
+
+  return {
+    // 要素一：base 与 Nginx location 对齐
+    base: isProd ? '/{domain}app/' : '/',
+    plugins: [
+      vue(),
+      // 要素二：iceStarkHtmlFixPlugin
+      iceStarkHtmlFixPlugin(),
+      ...(isProd ? [compression({ ext: '.gz', algorithm: 'gzip', threshold: 10240, level: 9 })] : []),
+      AutoImport({
+        imports: ['vue', 'vue-router', 'pinia'],
+        resolvers: [ElementPlusResolver()],
+        dts: 'src/types/auto-imports.d.ts',
+      }),
+      Components({
+        resolvers: [ElementPlusResolver()],
+        dts: 'src/types/components.d.ts',
+      }),
+    ],
+    resolve: {
+      alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
+    },
+    // @ice/stark-data 为 CommonJS，预构建后才能正确解析 named export
+    optimizeDeps: { include: ['@ice/stark-data'] },
+    server: {
+      port: {PORT},
+      host: '127.0.0.1',
+      cors: true,
+      // 允许主应用跨域加载子应用资源
+      headers: { 'Access-Control-Allow-Origin': '*' },
+      proxy: {
+        '/nebula-{domain}': {
+          target: env.VITE_{DOMAIN}_BACKEND || 'http://localhost:8080',
+          changeOrigin: true,
+          ...(needRewrite ? { rewrite: (p: string) => p.replace(/^\/nebula-{domain}/, '') } : {}),
+        },
+      },
+    },
+    build: {
+      target: 'es2015',
+      chunkSizeWarningLimit: 1000,
+      rollupOptions: {
+        // 要素三：双 Rollup 入口 + preserveEntrySignatures
+        input: {
+          index: fileURLToPath(new URL('./index.html', import.meta.url)),
+          main: fileURLToPath(new URL('./src/main.ts', import.meta.url)),
+        },
+        preserveEntrySignatures: 'exports-only',
+      },
+    },
+  }
+})
+```
+
+**iceStarkHtmlFixPlugin 原理**：
+- Vite 把 `index.html` 作为入口时，会生成 `index-{hash}.js`（**无导出**）和 `main-{hash}.js`（**有 mount/unmount 导出**）两个 facade
+- 默认 HTML 引用了无导出的 `index-xxx.js`，IceStark `import()` 拿不到 mount/unmount → 白屏
+- 此插件在 `writeBundle` 阶段把 HTML 里的 index facade 替换为 main facade
+
+### 3.3 src/main.ts 四个钩子
+
+```typescript
+import { createApp, type App as VueApp } from 'vue'
+import { createRouter, createWebHistory } from 'vue-router'
+import { createPinia } from 'pinia'
+import ElementPlus from 'element-plus'
+import zhCn from 'element-plus/es/locale/lang/zh-cn'
+import NebulaComponents from '@nebula-web/components'
+import isInIcestark from '@ice/stark-app/lib/isInIcestark'
+import getBasename from '@ice/stark-app/lib/getBasename'
+import setLibraryName from '@ice/stark-app/lib/setLibraryName'
+import App from './App.vue'
+import routes from './router/routes'
+
+// 钩子一：库名（与主应用 microAppConfig.name 完全一致）
+setLibraryName('nebula{Domain}App')
+
+let vueApp: VueApp | null = null
+
+function createVueApp(basename: string) {
+  const router = createRouter({ history: createWebHistory(basename), routes })
+  const app = createApp(App)
+  app.use(createPinia())
+     .use(router)
+     .use(ElementPlus, { locale: zhCn })
+     .use(NebulaComponents)
+  return { app, router }
+}
+
+// 钩子二：safeUnmount（处理 HMR 双挂载 / DOM 残留）
+function safeUnmount(container?: HTMLElement) {
+  if (vueApp) { vueApp.unmount(); vueApp = null }
+  if (container && (container as any).__vue_app__) {
+    ;(container as any).__vue_app__.unmount()
+  }
+}
+
+// 钩子三：mount
+export function mount({ container }: { container: HTMLElement }) {
+  safeUnmount(container)
+  const { app } = createVueApp(getBasename())  // → '/{domain}app'
+  vueApp = app
+  app.mount(container)
+}
+
+// 钩子四：unmount
+export function unmount() { safeUnmount() }
+
+// 生产 Docker 环境 fallback
+;(window as any).nebula{Domain}App = { mount, unmount }
+
+// 独立运行模式（本地纯 UI 调试，不依赖主应用）
+if (!isInIcestark()) {
+  const { app } = createVueApp('/')
+  app.mount('#app')
+}
+```
+
+### 3.4 三套 .env
+
+**.env.development**（pnpm dev，本地内网 IP 后端）
+```env
+VITE_{DOMAIN}_API_BASE=
+VITE_{DOMAIN}_BACKEND=http://localhost:8080
+VITE_PROXY_REWRITE=true
+```
+
+**.env.remote**（pnpm dev:remote，联调线上）
+```env
+VITE_{DOMAIN}_API_BASE=
+VITE_{DOMAIN}_BACKEND=https://{your-host-domain}
+VITE_PROXY_REWRITE=false
+```
+
+**.env.production**
+```env
+VITE_{DOMAIN}_API_BASE=/nebula-{domain}
+```
+
+**.npmrc**
+```ini
+@nebula-web:registry=https://gitlab.{your-gitlab-host}/api/v4/packages/npm/
+//gitlab.{your-gitlab-host}/api/v4/packages/npm/:_authToken=${GITLAB_TOKEN}
+```
+
+### 3.5 src/api/index.ts
+
+```typescript
+import { createRequest } from '@nebula-web/utils'
+
+// 空字符串时回退到 /nebula-{domain}，由 proxy 转发
+export const {domain}Request = createRequest(
+  import.meta.env.VITE_{DOMAIN}_API_BASE || '/nebula-{domain}'
+)
+export const systemRequest = createRequest(
+  import.meta.env.VITE_{DOMAIN}_API_BASE || '/nebula-system'
+)
+```
+
+`createRequest` 内置：JWT 注入、`X-Tenant-Id` 注入、401 静默刷新、`R<T>` 解包。**不要自己 axios.create**。
+
+### 3.6 index.html（极简）
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1.0" />
+  <title>nebula-{domain}-web</title>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/main.ts"></script>
+</body>
+</html>
+```
+
+---
+
+## 四、主应用注册步骤
+
+修改 `nebula-web/apps/nebula-web-main/src/layout/tabs/microAppConfig.ts`，追加：
+
+```typescript
+const microApps = [
+  // ... 已有
+  {
+    name: '{domain}app',                     // ← 与 setLibraryName 去掉前缀和大写后一致
+    activePath: '/{domain}app',
+    title: '{业务中文名}',
+    entry: 'VITE_MICRO_APP_{DOMAIN}',
+  },
+]
+```
+
+修改 `nebula-web/apps/nebula-web-main/.env.development`：
+```env
+VITE_MICRO_APP_{DOMAIN}={PORT}
+```
+
+修改 `nebula-web/apps/nebula-web-main/.env.production`：
+```env
+VITE_MICRO_APP_{DOMAIN}=/{domain}app/
+```
+
+---
+
+## 五、本地联调（两个仓库同时启动）
+
+```bash
+# 终端 1：主应用
+cd /path/to/nebula-web
+pnpm dev            # 主应用 :3000 + 内置 auth/system 子应用
+
+# 终端 2：业务子应用
+cd /path/to/nebula-{domain}-web
+pnpm dev            # :{PORT}
+```
+
+打开 `http://127.0.0.1:3000/` → 登录 → 菜单点击「{业务中文名}」→ 主应用通过 IceStark `import('http://127.0.0.1:{PORT}/')` 加载子应用。
+
+**两端 mode 必须一致**：主应用 `pnpm dev:remote` 时子应用也必须 `pnpm dev:remote`，否则后端代理目标不一致。
+
+---
+
+## 六、与主应用通信
+
+### 6.1 共享状态（store）
+
+主应用在登录 / 切换租户后通过 `@ice/stark-data` 推送：
+
+```typescript
+// 主应用（已实现，子应用直接读即可）
+import { store } from '@ice/stark-data'
+store.set('nebulaToken', accessToken)
+store.set('nebulaUser', userInfo)
+store.set('nebulaPermissions', ['xxx:read', 'xxx:write'])
+store.set('nebulaRoles', ['admin'])
+store.set('nebulaTenantId', tenantId)
+store.set('nebulaAuthBaseURL', '/nebula-auth')
+```
+
+子应用读取：
+```typescript
+import { store } from '@ice/stark-data'
+const token = store.get('nebulaToken')
+const perms = store.get('nebulaPermissions') ?? []
+```
+
+> 实际开发中，子应用基本不需要直接读 store —— `@nebula-web/utils` 的 `createRequest` 已经在拦截器里自动从 store 拿 token。
+
+### 6.2 事件（event）
+
+子应用主动通知主应用：
+
+```typescript
+import { event } from '@ice/stark-data'
+
+event.emit('401ToLogin', 'token 已失效')   // 跳登录
+event.emit('toLogout')                      // 主动登出
+event.emit('routerPush', '/dashboard')      // 主应用路由跳转
+event.emit('setGlobalLoading', true)        // 全局 loading
+```
+
+---
+
+## 七、命名一致性约束（最易翻车）⚠️
+
+下面五处命名必须严格对齐，**任一不一致都会导致 IceStark 加载白屏**：
+
+| 位置 | 取值规则 | 示例（`{domain}=mes`） |
+|------|---------|-----------------------|
+| 子应用 `src/main.ts` | `setLibraryName('nebula{PascalDomain}App')` | `setLibraryName('nebulaMesApp')` |
+| 主应用 `microAppConfig.ts` | `name: '{domain}app'`（剥除前缀 / 全小写） | `name: 'mesapp'` |
+| 主应用 `microAppConfig.ts` | `activePath: '/{domain}app'` | `activePath: '/mesapp'` |
+| 子应用 `vite.config.ts` | `base: isProd ? '/{domain}app/' : '/'` | `base: '/mesapp/'` |
+| 生产 Nginx | `location /{domain}app/ { ... }` | `location /mesapp/` |
+| 主应用 `.env.production` | `VITE_MICRO_APP_{DOMAIN}=/{domain}app/` | `VITE_MICRO_APP_MES=/mesapp/` |
+
+派生约定：
+- `{PascalDomain}` = 首字母大写（`mes` → `Mes`，`scm` → `Scm`）
+- `{domain}app` = 全小写
+- `{DOMAIN}` = 全大写
+
+---
+
+## 八、部署
+
+### 8.1 deploy/build-deploy.sh 骨架
+
+```bash
+#!/bin/bash
+# 编译并发布到 Nginx 服务器
+set -e
+
+SERVER_HOST="${SERVER_HOST:-}"          # 必填：通过环境变量传入
+SERVER_USER="${SERVER_USER:-ecs-user}"
+SERVER_PORT="${SERVER_PORT:-22}"
+REMOTE_HTML_BASE="${REMOTE_HTML_BASE:-/data/service/nginx/html/nebula-web/{domain}}"
+
+if [ -z "$SERVER_HOST" ]; then
+  echo "❌ 请设置 SERVER_HOST 环境变量"
+  exit 1
+fi
+
+# 1. 检查工具
+command -v pnpm >/dev/null || { echo "❌ pnpm 未安装"; exit 1; }
+command -v scp  >/dev/null || { echo "❌ scp 未安装";  exit 1; }
+command -v ssh  >/dev/null || { echo "❌ ssh 未安装";  exit 1; }
+
+# 2. 安装依赖（可选 -u 更新 @nebula-web/*）
+if [ "$1" = "-u" ]; then
+  export GITLAB_TOKEN="${GITLAB_TOKEN:?需要设置 GITLAB_TOKEN}"
+  pnpm update @nebula-web/components @nebula-web/types @nebula-web/utils
+else
+  pnpm install
+fi
+
+# 3. 类型检查（可选 -f 跳过）
+[ "$1" != "-f" ] && pnpm typecheck
+
+# 4. 编译
+pnpm build
+
+# 5. 上传
+ssh -p "$SERVER_PORT" "$SERVER_USER@$SERVER_HOST" "mkdir -p $REMOTE_HTML_BASE"
+scp -P "$SERVER_PORT" -r dist/* "$SERVER_USER@$SERVER_HOST:$REMOTE_HTML_BASE/"
+
+echo "✅ 已发布到 $SERVER_HOST:$REMOTE_HTML_BASE"
+```
+
+### 8.2 Nginx 配置
+
+```nginx
+location /{domain}app/ {
+  alias /data/service/nginx/html/nebula-web/{domain}/;
+  try_files $uri $uri/ /{domain}app/index.html;
+  gzip_static on;
+}
+
+# 后端代理（与开发 proxy 路径一致）
+location /nebula-{domain}/ {
+  proxy_pass http://{backend-upstream}/;
+  proxy_set_header Authorization $http_authorization;
+  proxy_set_header X-Real-IP $remote_addr;
+}
+```
+
+---
+
+## 九、避坑清单（本主题专属）
+
+- ⚠️ `setLibraryName` 与 `microAppConfig.name` 不一致 → 主应用 `import()` 后拿不到 mount/unmount → 白屏
+- ⚠️ `vite.config.ts` 漏掉双 Rollup 入口或 `preserveEntrySignatures: 'exports-only'` → 同上
+- ⚠️ 漏掉 `iceStarkHtmlFixPlugin` → 生产构建后 HTML 引用错误 facade → 白屏
+- ⚠️ `optimizeDeps.include` 没加 `@ice/stark-data` → 开发模式 named export 解析失败
+- ⚠️ `main.ts` 的 `mount` 没 safeUnmount → HMR 后双挂载 / DOM 残留
+- ⚠️ 业务代码直接用 `axios.create` → 应使用 `@nebula-web/utils` 的 `createRequest`
+- ⚠️ 直接读 `localStorage.getItem('token')` → 应通过 `@ice/stark-data` store 或 `@nebula-web/utils` 的 token helper
+- ⚠️ `.npmrc` 没配 `GITLAB_TOKEN` → `pnpm install` 拉不到 `@nebula-web/*`
+- ⚠️ 主子应用 mode 不一致（一边 dev，一边 dev:remote）→ 接口请求落到错误后端
+- ⚠️ 子应用 `index.html` 标题、`README.md`、`package.json` 描述、UI 字面量中残留其他业务样板字眼 → 必须替换为当前业务名
+
+详尽避坑参考 [pitfalls-checklist.md](pitfalls-checklist.md) §G。