@gct-paas/core

PaaS 平台工程开发公共底包。提供全局运行时对象 _gct、Pinia 状态、路由/i18n 脚手架、环境管理、MQTT、HTTP 拦截、BEM 命名空间及各类工具方法。上层包（core-web / core-mobile / design / render 等）均依赖本包。

本文档面向后续开发与 AI 模型阅读：说明依赖用途、全局 _gct 能力与典型用法。

包信息

| 项 | 值 | | --- | --- | | 包名 | @gct-paas/core | | 入口 | es/index.mjs（类型：es/index.d.ts） | | 全局类型 | @gct-paas/core/types → es/types/index.d.ts | | CDN/loader | dist/index.esm.min.js | | peer | vue>=3、vue-i18n>=11、vue-router>=4、@gct-paas/api |

import { setupApp, createAppVue, useNamespace, t } from '@gct-paas/core';
// 引入本包后会自动执行 onInit()，挂载 window._gct / window._api

在 monorepo 中的位置

core                          ← 本包：平台无关公共逻辑与全局运行时
 ├── core-components
 ├── core-web / core-mobile / core-pad   ← 会挂载 message / confirm / openUtil 等端侧实现
 │     ├── design / design-*
 │     └── render / render-*
 ├── scss / schema / v-ben / native

兄弟底包说明文档见各 packages/*/README.md（如 core-web、design、render、schema、scss 等）。

依赖说明（供模型选型）

Peer Dependencies（宿主必须提供）

| 依赖 | 用途 | 典型用法 | | --- | --- | --- | | vue | 应用框架 | setupApp / createAppVue | | vue-router | 路由 | _gct.router、RouterUtil | | vue-i18n | 多语言 | _gct.i18n、t()、window.$t | | @gct-paas/api | OpenAPI 生成的 API 客户端 | _gct.api / window._api（只读） |

@gct-paas/api 通过 pnpm catalog 管理版本（见仓库根 pnpm-workspace.yaml）。全局类型中拆分为：

• _api.apaas — aPaaS / 设计器相关 API
• _api.platform — 平台（租户、用户等）API

Runtime Dependencies

| 依赖 | 用途 | 在 core 中的落点 | | --- | --- | --- | | pinia | 全局/平台配置状态 | _gct.store、_gct.platformStore、GlobalStoreUtil | | axios | HTTP（经 @gct-paas/api 的 HttpUtil） | interceptors、状态码处理 | | mqtt | MQTT 客户端 | _gct.mqtt（MqttManager） | | wujie | 微前端子应用通信类型 | window.$wujie、useWuJieBus 等 hooks | | dayjs | 日期处理 | 工具/业务时间逻辑 | | lodash-es | 通用工具 | 深合并等 | | mitt | 事件总线 | mitt 导出 | | qs | querystring | 请求参数序列化 | | async-validator | 表单/规则校验 | validate / lowcode 规则 | | nprogress | 页面加载进度条 | 路由守卫相关 | | overlayscrollbars | 自定义滚动条 | UI 辅助 | | @vueuse/core | Vue 组合式工具 | hooks | | @floating-ui/dom | 浮层定位 | overlay / popover | | @fingerprintjs/fingerprintjs | 浏览器指纹 | 签到日志、MQTT 踢人等 | | js-sha256 | 哈希 | 签名/校验场景 | | qx-util | UUID 等小工具 | MQTT clientId 等 | | @module-federation/runtime | 模块联邦（代码中暂注释） | 预留 _gct.mf |

不要直接替代的能力

• API 调用：优先 _gct.api / _api，不要在业务里再包一层裸 axios（除非扩展拦截器）。
• 多语言：用 t() 或 _gct.i18n，不要另建 i18n 实例覆盖全局（主项目可挂载正式实例到 _gct.i18n）。
• BEM 类名：用 useNamespace('block')，不要手写 gct-xxx 拼接。
• 环境判断：用 _gct.env（isSandbox / isTestEnv / getEnv() 等），不要散落解析 URL。

源码结构

packages/core/src/
├── index.ts              # 导出 + 自动 onInit → window._gct
├── global/gct/gct.ts     # GctGlobal 类定义
├── setup-app.ts          # 应用启动：拦截器、_gct.init、平台配置、locale
├── create-app-vue.ts     # 挂 i18n + router
├── modules/
│   ├── env-manager/      # 环境检测（dev/test/prod/sbx）
│   ├── error-handler/    # 错误处理策略
│   ├── mqtt/             # MqttManager / MqttClient
│   ├── system-mqtt/      # 系统级 MQTT（踢人、站内信等）
│   ├── sign-log/         # 签到/登录日志
│   ├── platform-config/  # 平台配置 store + composables
│   └── user-stores/      # user / tenant / permission store
├── store/                # GlobalStoreUtil、session/local storage 辅助
├── router/               # RouterUtil、守卫
├── locale/               # LocaleUtil、core 文案自动注册
├── utils/                # axios、namespace、uploader、treeHelper…
├── hooks/                # useModal、useWuJie*、useAppInst…
├── constants/ / enums/ / interface/ / types/
└── types/index.d.ts      # Window / 全局 _gct、_api、$t、$wujie 声明

全局对象：_gct / _api

初始化时机

引入 @gct-paas/core（或其依赖方）时，index.ts 会同步执行 onInit()：

1. 若已存在 window._gct，打印警告并跳过。
2. 否则 window._gct = new GctGlobal()。
3. 将 api（来自 @gct-paas/api）以只读 getter 挂到：
   • window._gct.api
   • window._api

全局类型声明（packages/core/src/types/index.d.ts）使业务代码可直接写 _gct、_api，无需 import。

GctGlobal 成员一览

| 成员 | 类型/实现 | 说明 | | --- | --- | --- | | store | Pinia global-store | 上下文 context、用户、应用信息、pageLoading 等 | | platformStore | 平台配置 store | 主题/登录/组织/水印等平台级配置 | | storeUtil | GlobalStoreUtil | 持有 pinia 实例与上述 store | | router / routerUtil | vue-router | 全局路由 | | i18n / i18nUtil | vue-i18n | 默认轻量实例；正式文案由主项目/setup 挂载与注册 | | env | EnvironmentManager | 环境、单应用、沙箱、Android 混合模式等 | | mqtt | MqttManager | 多实例 MQTT 创建/获取/销毁 | | dictionary | DictionaryUtil | 数据字典 | | api | ApiMap（只读） | 同 _api | | register | IGlobalRegister | 注册中心；端侧包可挂载 editor/formItem 等 | | message | IMessageUtil | 需端侧挂载（如 @gct-paas/core-web） | | confirm | IConfirmUtil | 需端侧挂载 | | openUtil | IOverlayController | 需端侧挂载（弹层/抽屉等） |

异步初始化：

await _gct.init();
// 内部：store.init() → env.checkIsTestEnv() → i18nUtil.init()

通常不要单独调用，应走 setupApp(app)。

端侧挂载示例（core-web）

@gct-paas/core-web 引入时会补充 UI 能力：

_gct.confirm = new ConfirmUtil();
_gct.message = new MessageUtil();
_gct.openUtil = overlay;
_gct.register.editor = new EditorRegister();
// …

在仅依赖 core、未加载对应端侧包的环境中，调用 _gct.message / confirm / openUtil 会失败——模型生成代码时需确认宿主已加载端侧包。

其他全局

| 全局 | 说明 | | --- | --- | | _api | 与 _gct.api 相同，只读 | | window.$t | 同 t()，非组件上下文翻译 | | window.$wujie | 作为 wujie 子应用运行时由容器注入 | | window.__GCT_ANDROID__ | 原生注入；_gct.env.isAndroid 读取 |

应用启动流程（推荐）

import { createApp } from 'vue';
import { setupApp, createAppVue } from '@gct-paas/core';
// 按端引入，挂载 message/confirm/openUtil
import '@gct-paas/core-web';

const app = createApp(Root);

await setupApp(app);
// 1. HttpUtil.use(interceptors)
// 2. await _gct.init()
// 3. registerCoreLocale()
// 4. await platformConfigStore.init()

createAppVue(app);
// provide APP_INST + setupI18n + setupRouter

app.mount('#app');

插件模块约定接口（见 IKitPluginModule）：同样暴露 setupApp / createAppVue。

_gct 常用用法

环境与上下文

const env = _gct.env.getEnv(); // 'dev' | 'test' | 'prod' | 'sbx'
if (_gct.env.isSandbox || _gct.env.isAppSingle) { /* … */ }
if (_gct.env.isAndroid) { /* 混合 App */ }

const { aid, bid, env: ctxEnv, mode } = _gct.store.context;
await _gct.store.setContext({ aid: 'xxx' });

用户与应用

const userId = _gct.store.userInfo?.userId;
const appId = _gct.store.appInfo?.id;
_gct.store.setPageLoading(true);

另有独立 Pinia store（可从包导出使用）：

• useUserStore / useTenantStore / usePermissionStore
• usePlatformConfigStore（亦挂于 _gct.platformStore）

API

// 推荐
const app = await _api.apaas.designerCommon.getGetApp();
const tenant = await _api.platform.tenant.getInfoByPortOrDomain({ domain });

// 等价
await _gct.api.apaas.basicConfig.getDetail({ configEnum });

消息 / 确认 / 弹层

_gct.message.error('失败');
await _gct.confirm.confirm({ /* … */ }); // 以端侧 IConfirmUtil 为准
_gct.openUtil.open(/* overlay 选项 */);

MQTT

const client = _gct.mqtt.create('my-instance', {
  username: '…',
  password: '…',
});
const off = client.subscribe('topic/#', (topic, payload) => { /* … */ });
await client.publish('topic/cmd', 'on');
_gct.mqtt.destroy('my-instance');

多语言

import { t } from '@gct-paas/core';

t('sys.xxx');
window.$t('sys.xxx');
_gct.i18n.global.t('sys.xxx');

BEM 命名空间

import { useNamespace } from '@gct-paas/core';

const ns = useNamespace('button');
ns.b();           // gct-button
ns.e('icon');     // gct-button__icon
ns.m('primary');  // gct-button--primary
ns.is('disabled', true);

主要导出速查

从 @gct-paas/core 可直接 import（完整列表以 src/index.ts 为准）：

| 类别 | 示例 | | --- | --- | | 启动 | setupApp、createAppVue、GctGlobal | | 模块 | EnvironmentManager、EnvironmentType、MqttManager、usePlatformConfigStore、useUserStore… | | Store 辅助 | globalRefStorage、globalRefSession、ENV | | 工具 | useNamespace、t、mitt、cssLoader、TreeHelper、AuthUtil、interceptors、getToken/setToken、gctMemoizeAsync、PluginPgkUtil… | | Hooks | useModal、useAppInst、useWuJieBus、useWuJieProps… | | 常量/枚举/接口 | constants/*、enums/*、interface/* | | 路由常量 | REDIRECT_NAME |

给后续模型的约束摘要

1. 全局单例：业务侧读写运行时状态优先 _gct.* / _api，不要新建第二套全局。
2. 不要改写 _gct.api / _api：属性为只读，赋值会抛错。
3. 端侧能力：message / confirm / openUtil / 部分 register.* 由 core-web 等包挂载，生成代码前确认宿主依赖链。
4. 启动顺序：setupApp → createAppVue → mount；在 setupApp 完成前不要依赖已初始化的 env/平台配置。
5. 类型：需要全局声明时引用 @gct-paas/core/types（或宿主已引入的全局类型）。
6. 样式：组件类名走 useNamespace；SCSS 侧遵循仓库 BEM skill（.agents/skills/gct-bem-best）。
7. 导入：禁止从 @/index、@/loader、父目录 .. 导入（ESLint 限制）；跨包用包名 @gct-paas/core。

本地命令

cd packages/core
npm run dev          # watch
npm run build        # lint + vue-tsc + 双 Vite 构建
npm run lint
npm run test:run
npm run test:coverage