@gct-paas/core 0.1.6-dev.9 → 6.0.0-dev.2

package/README.md

@@ -1 +1,323 @@
+# @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` |
+
+```ts
+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` | **需端侧挂载**（弹层/抽屉等） |
+
+异步初始化：
+
+```ts
+await _gct.init();
+// 内部：store.init() → env.checkIsTestEnv() → i18nUtil.init()
+```
+
+通常不要单独调用，应走 `setupApp(app)`。
+
+### 端侧挂载示例（core-web）
+
+`@gct-paas/core-web` 引入时会补充 UI 能力：
+
+```ts
+_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` 读取 |
+
+---
+
+## 应用启动流程（推荐）
+
+```ts
+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` 常用用法
+
+### 环境与上下文
+
+```ts
+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' });
+```
+
+### 用户与应用
+
+```ts
+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
+
+```ts
+// 推荐
+const app = await _api.apaas.designerCommon.getGetApp();
+const tenant = await _api.platform.tenant.getInfoByPortOrDomain({ domain });
+
+// 等价
+await _gct.api.apaas.basicConfig.getDetail({ configEnum });
+```
+
+### 消息 / 确认 / 弹层
+
+```ts
+_gct.message.error('失败');
+await _gct.confirm.confirm({ /* … */ }); // 以端侧 IConfirmUtil 为准
+_gct.openUtil.open(/* overlay 选项 */);
+```
+
+### MQTT
+
+```ts
+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');
+```
+
+### 多语言
+
+```ts
+import { t } from '@gct-paas/core';
+
+t('sys.xxx');
+window.$t('sys.xxx');
+_gct.i18n.global.t('sys.xxx');
+```
+
+### BEM 命名空间
+
+```ts
+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`。
+
+---
+
+## 本地命令
+
+```bash
+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
+```