@hhhpyb/system-assistant-client 1.3.6

package/README.md

@@ -0,0 +1,86 @@
+# @hhhpyb/system-assistant-client
+
+Nuxt 2 客户端插件：自动加载 [sa-guide-sdk](https://www.npmjs.com/package/sa-guide-sdk) bootstrap，并在路由切换后刷新指引。
+
+## 安装
+
+```bash
+npm install @hhhpyb/system-assistant-client
+```
+
+## Nuxt 2 接入
+
+### 1. 注册模块
+
+`nuxt.config.js`：
+
+```js
+export default {
+  modules: [
+    '@hhhpyb/system-assistant-client/nuxt',
+  ],
+}
+```
+
+无需在 `nuxt.config.js` 中配置 `SA_GUIDE_APP_KEY`。模块会在构建时自动将应用标识注入 Nuxt 运行时配置。
+
+模块还会自动接入 `@hhhpyb/guide-compiler`：Nuxt 2/Bridge 的 Webpack 与 Vite 客户端构建均会在不重复挂载的前提下生成 `.nuxt/sa-guide-manifest.json`，无需在业务项目中配置 compiler loader 或 Vite plugin。
+
+### 应用标识推导
+
+`SA_GUIDE_APP_KEY` 按以下优先级确定：
+
+1. `nuxt.config.js` 中已显式配置的 `env.SA_GUIDE_APP_KEY`；
+2. 构建环境变量 `SA_GUIDE_APP_KEY`；
+3. 业务项目根目录 `package.json` 的 `name`；
+4. 项目根目录名（构建时会输出明确警告）。
+
+包名会规范化为安全短标识：npm scope 会被移除，例如 `@company/ehr` 会得到 `ehr`。不会根据域名推导应用标识。
+
+### 可选配置
+
+仅在需要覆盖默认 API 或 Studio 管理后台 origin 时，在 `nuxt.config.js` 中配置：
+
+```js
+export default {
+  env: {
+    SA_GUIDE_API_BASE: process.env.SA_GUIDE_API_BASE || 'http://127.0.0.1:8000',
+    SA_GUIDE_EDITOR_PARENT_ORIGIN: process.env.SA_GUIDE_EDITOR_PARENT_ORIGIN || '*',
+  },
+}
+```
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `SA_GUIDE_API_BASE` | 指引 API 根地址（可不含 `/system-assistant` 后缀） | `http://127.0.0.1:8000` |
+| `SA_GUIDE_APP_KEY` | 可选的应用标识覆盖值 | 自动推导 |
+| `SA_GUIDE_EDITOR_PARENT_ORIGIN` | Studio 配置态管理后台 origin | `*` |
+
+### Studio 配置态
+
+URL 带 `?sa_studio=1` 时自动进入 Studio 点选模式，支持 `sa_app_key`、`sa_api`、`sa_origin` 查询参数覆盖。
+
+## 行为说明
+
+- 仅客户端执行（`process.server` 时跳过）
+- 从 `{apiBase}/sdk/v1/bootstrap.js` 加载 SDK
+- 普通模式：调用 `SystemAssistantBootstrap.start()`
+- 路由 `afterEach` 后自动调用 `SystemAssistant.checkAllContexts()` 刷新指引
+
+## 发布（维护者）
+
+源码：`system-assistant/deployables/sa-guide-sdk/app/v1/system-assistant.client.js`
+
+```bash
+cd packages/system-assistant-client
+
+# 1. 更新 sa-guide-sdk/app/v1/system-assistant.client.js 中的 SA_GUIDE_ASSET_VERSION
+# 2. 同步 package.json version
+npm run build
+npm login
+npm publish --access public --registry=<npm-registry>
+```
+
+## 许可证
+
+MIT

package/dist/index.js

@@ -0,0 +1,87 @@
+const DEFAULT_API_BASE = 'http://127.0.0.1:8000';
+const DEFAULT_APP_KEY = 'ehr';
+const SA_GUIDE_ASSET_VERSION = '1.3.9';
+
+function normalizeApiBase(apiBase) {
+    const raw = (apiBase || DEFAULT_API_BASE).replace(/\/$/, '');
+    return raw.endsWith('/system-assistant') ? raw : `${raw}/system-assistant`;
+}
+
+function isStudioMode() {
+    const params = new URLSearchParams(window.location.search);
+    return params.get('sa_studio') === '1' || params.get('sa_studio') === 'true';
+}
+
+function loadBootstrap(apiBase) {
+    return new Promise((resolve, reject) => {
+        if (window.SystemAssistantBootstrap) {
+            resolve(window.SystemAssistantBootstrap);
+            return;
+        }
+
+        const existing = document.querySelector('script[data-sa-guide-bootstrap="1"]');
+        if (existing) {
+            existing.addEventListener('load', () => resolve(window.SystemAssistantBootstrap));
+            existing.addEventListener('error', reject);
+            return;
+        }
+
+        const script = document.createElement('script');
+        script.src = `${apiBase}/sdk/v1/bootstrap.js?v=${SA_GUIDE_ASSET_VERSION}`;
+        script.async = true;
+        script.dataset.saGuideBootstrap = '1';
+        script.onload = () => resolve(window.SystemAssistantBootstrap);
+        script.onerror = reject;
+        document.head.appendChild(script);
+    });
+}
+
+export default async function systemAssistantPlugin({ app, $config }) {
+    if (process.server) return;
+
+    const apiBase = normalizeApiBase($config && $config.SA_GUIDE_API_BASE);
+    const appKey = ($config && $config.SA_GUIDE_APP_KEY) || DEFAULT_APP_KEY;
+    const editorParentOrigin = ($config && $config.SA_GUIDE_EDITOR_PARENT_ORIGIN) || '*';
+
+    try {
+        window.SA_APP_KEY = appKey;
+        window.SA_WATCH_IFRAME = true;
+
+        const bootstrap = await loadBootstrap(apiBase);
+
+        const startStudio = async () => {
+            if (!isStudioMode()) return;
+            const params = new URLSearchParams(window.location.search);
+            const sdk = await bootstrap.loadSdk();
+            await sdk.startStudio({
+                appKey: params.get('sa_app_key') || appKey,
+                apiBase: params.get('sa_api') || apiBase,
+                adminOrigin: params.get('sa_origin') || editorParentOrigin,
+            });
+        };
+
+        if (isStudioMode()) {
+            await startStudio();
+        } else {
+            await bootstrap.start({
+                appKey,
+                apiBase,
+                watchIframe: true,
+            });
+        }
+
+        if (app.router) {
+            app.router.afterEach(() => {
+                window.setTimeout(() => {
+                    if (isStudioMode()) {
+                        startStudio();
+                        return;
+                    }
+                    window.SystemAssistant && window.SystemAssistant.checkAllContexts && window.SystemAssistant.checkAllContexts();
+                }, 300);
+            });
+        }
+    } catch (error) {
+        console.warn('[SystemAssistant] SDK load failed', error);
+    }
+}

package/nuxt.cjs

@@ -0,0 +1,127 @@
+const { resolve } = require('node:path')
+const { readFileSync } = require('node:fs')
+const setupGuideCompilerNuxt2 = require('@hhhpyb/guide-compiler/nuxt2')
+
+const APP_KEY_ENV = 'SA_GUIDE_APP_KEY'
+const GUIDE_COMPILER_WEBPACK_MARKER = Symbol.for('system-assistant.guide-compiler.webpack')
+const GUIDE_COMPILER_VITE_MARKER = Symbol.for('system-assistant.guide-compiler.vite')
+
+function normalizeAppKey(value) {
+  if (typeof value !== 'string') return ''
+
+  const packageName = value.trim().replace(/^@[^/]+\//, '')
+  return packageName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64)
+}
+
+function readProvidedAppKey(value) {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function readPackageName(rootDir) {
+  try {
+    const packageJson = JSON.parse(readFileSync(resolve(rootDir, 'package.json'), 'utf8'))
+    return normalizeAppKey(packageJson.name)
+  } catch (_error) {
+    return ''
+  }
+}
+
+function resolveAppKey({ configuredAppKey, environmentAppKey, rootDir }) {
+  const explicitAppKey = readProvidedAppKey(configuredAppKey)
+  if (explicitAppKey) return { appKey: explicitAppKey, source: 'configured' }
+
+  const envAppKey = readProvidedAppKey(environmentAppKey)
+  if (envAppKey) return { appKey: envAppKey, source: 'environment' }
+
+  const packageAppKey = readPackageName(rootDir)
+  if (packageAppKey) return { appKey: packageAppKey, source: 'package' }
+
+  return { appKey: normalizeAppKey(rootDir.split(/[\\/]/).filter(Boolean).pop()) || 'app', source: 'directory' }
+}
+
+function createGuideCompilerOptions(rootDir, appKey) {
+  return {
+    enabled: true,
+    appKey,
+    idPrefix: appKey,
+    rootDir,
+    include: ['pages', 'components', 'layouts'],
+    exclude: ['node_modules', '.nuxt', '.output'],
+    manifestOutput: resolve(rootDir, '.nuxt/sa-guide-manifest.json'),
+    manifestAsset: 'sa-guide-manifest.json',
+    productionDuplicatePolicy: 'block_manual',
+    sensitiveWords: ['薪资', '工资', '金额', '审批结论', '身份证', '手机号'],
+  }
+}
+
+function installGuideCompilerWebpack(config, options) {
+  if (!config || config[GUIDE_COMPILER_WEBPACK_MARKER]) return config
+  setupGuideCompilerNuxt2(config, options)
+  Object.defineProperty(config, GUIDE_COMPILER_WEBPACK_MARKER, { value: true })
+  return config
+}
+
+async function installGuideCompilerVite(config, options) {
+  if (!config || config[GUIDE_COMPILER_VITE_MARKER]) return config
+  const { systemAssistantGuideVitePlugin } = await import('@hhhpyb/guide-compiler/vite')
+  config.plugins = config.plugins || []
+  if (!config.plugins.some((plugin) => plugin && plugin.name === 'system-assistant-guide-compiler')) {
+    config.plugins.push(systemAssistantGuideVitePlugin(options))
+  }
+  Object.defineProperty(config, GUIDE_COMPILER_VITE_MARKER, { value: true })
+  return config
+}
+
+module.exports = function systemAssistantClientModule() {
+  const rootDir = this.options.rootDir || process.cwd()
+  const env = this.options.env || (this.options.env = {})
+  const result = resolveAppKey({
+    configuredAppKey: env[APP_KEY_ENV],
+    environmentAppKey: process.env[APP_KEY_ENV],
+    rootDir,
+  })
+
+  env[APP_KEY_ENV] = result.appKey
+  const guideCompilerOptions = createGuideCompilerOptions(rootDir, result.appKey)
+
+  if (this.nuxt && typeof this.nuxt.hook === 'function') {
+    this.nuxt.hook('webpack:config', (config) => {
+      installGuideCompilerWebpack(config, guideCompilerOptions)
+    })
+    this.nuxt.hook('vite:extendConfig', async (config, context) => {
+      if (!context || context.isClient !== true) return
+      await installGuideCompilerVite(config, guideCompilerOptions)
+    })
+  }
+
+  if (result.source === 'directory') {
+    // Nuxt builds can still proceed when a project omits package.json.name, but
+    // the derived key is less stable than a package name and must be visible.
+    // eslint-disable-next-line no-console
+    console.warn(`[system-assistant-client] package.json name is unavailable; using directory name as SA_GUIDE_APP_KEY: ${result.appKey}`)
+  }
+
+  this.addPlugin({
+    src: resolve(__dirname, 'dist/index.js'),
+    fileName: 'system-assistant.client.js',
+    mode: 'client',
+  })
+}
+
+module.exports.meta = {
+  name: '@hhhpyb/system-assistant-client',
+}
+
+module.exports._internal = {
+  normalizeAppKey,
+  readProvidedAppKey,
+  readPackageName,
+  resolveAppKey,
+  createGuideCompilerOptions,
+  installGuideCompilerWebpack,
+  installGuideCompilerVite,
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@hhhpyb/system-assistant-client",
+  "version": "1.3.6",
+  "description": "Nuxt 2 client plugin for System Assistant smart guide SDK",
+  "keywords": [
+    "nuxt",
+    "nuxt2",
+    "guide",
+    "system-assistant",
+    "plugin"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "http://git.ymdd.tech/twg195158/smart-guide-assistant.git",
+    "directory": "system-assistant-front/packages/system-assistant-client"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "nuxt.cjs"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./nuxt": "./nuxt.cjs"
+  },
+  "peerDependencies": {
+    "nuxt": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "nuxt": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@hhhpyb/guide-compiler": "0.1.0"
+  },
+  "scripts": {
+    "build": "node scripts/copy-dist.js",
+    "test": "node --test test/nuxt.test.cjs",
+    "prepublishOnly": "npm run build"
+  }
+}