npm package: @skyfox2000/microbase
Description: 微前端通用功能与数据类型定义
Author: skyfox2000@github.com
Latest version: 1.6.7

# 微前端基础类型库 (@skyfox2000/microbase)

## 项目概述

这是一个专为微前端架构设计的基础类型库，提供了微前端应用间通信、数据类型定义、路由管理和模块加载等核心功能。该库是微前端生态系统的基础组件，为主应用和子应用之间的协作提供标准化的接口和数据结构。

## 核心特性

### 🔗 微前端通信
- **统一通讯方式**：所有API调用统一使用 `forceDispatch` 发送 + `addDataListener` 监听响应
- **类型安全调用**：提供 `mainAppApis` 类型安全的API接口
- **Promise支持**：所有API调用返回Promise，支持async/await语法
- **环境检测**：自动检测当前运行环境（独立应用/微应用/基座应用）

### 📋 类型定义体系
- **应用信息类型**：完整的应用元数据类型定义
- **用户信息类型**：用户认证和权限相关类型
- **主机信息类型**：环境配置和服务地址类型
- **设置信息类型**：前端配置和偏好设置类型

### 🛠 工具函数集合
- **数据处理**：参数组合、数据转换等工具函数
- **环境管理**：环境变量统一管理和配置
- **路由加载**：动态路由加载和管理
- **模块加载**：支持动态模块加载和组件注册

## 安装使用

### 安装方式
```bash
npm install -S @skyfox2000/microbase
```

### 基本使用
```typescript
import { 
  isMicroApp, 
  initMainAppData, 
  initMicroAppProxy,
  mainAppApis,
  AppInfo,
  UserInfo 
} from '@skyfox2000/microbase';

// 检测是否在微应用环境中运行
if (isMicroApp()) {
  // 初始化微应用通讯层（包含数据监听和请求代理）
  initMainAppData();
  initMicroAppProxy();
  
  // 使用类型安全的API接口
  const userInfo = await mainAppApis.getUserInfo();
  console.log('当前用户:', userInfo);
  
  // 或使用通用调用方法
  const hostInfo = await mainAppApis.call<HostInfo>('getHostInfo');
}
```

## API 文档

### 环境检测函数

#### `isMicroApp(): boolean`
检测当前应用是否运行在微前端环境中
```typescript
if (isMicroApp()) {
  console.log('运行在微前端环境');
}
```

#### `isBaseMicroApp(): boolean`
检测当前应用是否为微前端基座应用
```typescript
if (isBaseMicroApp()) {
  console.log('当前是基座应用');
}
```

### 主应用通信

#### `initMainAppData(): void`
初始化主应用数据，获取初始页面地址等信息
```typescript
// 在微应用启动时调用
initMainAppData();
```

#### `initMicroAppProxy(): void`
初始化微应用通讯层，设置数据监听和请求代理
```typescript
// 在微应用启动时调用，必须在 initMainAppData 之后
initMicroAppProxy();
```

#### `mainAppApis` - 主应用开放API接口

`mainAppApis` 提供了所有主应用API的类型安全调用方法：

```typescript
// 获取主机信息
const hostInfo = await mainAppApis.getHostInfo();

// 获取应用信息
const appInfo = await mainAppApis.getAppInfo();

// 获取用户信息
const userInfo = await mainAppApis.getUserInfo();

// 获取授权令牌
const token = await mainAppApis.getToken();

// 获取设置信息
const settingInfo = await mainAppApis.getSettingInfo();

// 用户登录
const loginResult = await mainAppApis.userLogin({
  UserName: 'admin',
  UserPass: 'password'
});

// 用户登出
await mainAppApis.userLogout();

// 路由跳转
await mainAppApis.mainAppPush('/target-path');
```

#### `callMainAppApi` - 通用API调用

用于调用未预定义的API方法：

```typescript
import { callMainAppApi } from '@skyfox2000/microbase';

// 通用调用
const result = await callMainAppApi('customMethod', { param1: 'value1' });

// 带类型的调用
const typedResult = await callMainAppApi<CustomType>('customMethod', params);

// 带超时的调用（默认30000ms）
const result = await callMainAppApi('longRunningMethod', params, 60000);
```

### 环境配置

#### `EnvConfig: { [key: string]: string }`
统一的环境变量配置对象

#### `initEnv(metaEnv: ImportMetaEnv): void`
初始化环境变量配置
```typescript
import { initEnv } from '@skyfox2000/microbase';

// 在应用启动时初始化环境变量
initEnv(import.meta.env);
```

### 数据处理工具

#### `combineParams(params: any): any`
参数组合和处理工具函数
```typescript
import { combineParams } from '@skyfox2000/microbase';

const combinedParams = combineParams({
  param1: 'value1',
  param2: 'value2'
});
```

### 路由管理

#### `LoaderRouter`
动态路由加载器，支持路由的动态注册和管理
```typescript
import { LoaderRouter } from '@skyfox2000/microbase';

// 使用路由加载器
const router = new LoaderRouter(routeConfig);
```

### 模块加载

#### 模块加载器函数
```typescript
import { 
  loadModule, 
  initModuleLoader,
  moduleAttrs,
  moduleUrl,
  moduleRecords,
  moduleCom 
} from '@skyfox2000/microbase';

// 初始化模块加载器
initModuleLoader(import.meta.glob('./views/**/*.vue', { eager: false }));

// 动态加载模块
await loadModule('module-name');
```

## 类型定义

### AppInfo - 应用信息
```typescript
interface AppInfo {
  readonly Id: string;           // 应用唯一标识
  readonly Name: string;         // 应用名称
  readonly AppCode: string;      // 应用编码（路由前缀）
  readonly Version: string;      // 版本号
  readonly Icon: string;         // 应用图标
  readonly Source: AppSource;    // 应用来源
  readonly Action: AppAction;    // 应用动作类型
  readonly Host: string;         // 应用加载地址
  readonly Enabled: boolean | number; // 启用状态
  Page?: string;                 // 默认页面
  Default?: boolean;             // 是否默认应用
  Description?: string;          // 应用描述
}
```

### UserInfo - 用户信息
```typescript
interface UserInfo {
  readonly Id: string;           // 用户ID
  readonly Name: string;         // 用户名称
  readonly Code: string;         // 用户编码
  readonly TenantId: string | null; // 租户ID
  readonly UserLevel: string;    // 用户级别
  readonly Roles?: string[];     // 角色列表
  readonly Permissions?: string[]; // 权限列表
}
```

### LoginInfo - 登录信息
```typescript
interface LoginInfo {
  UserName: string;              // 用户名
  UserPass: string;              // 密码
  UserInfo?: UserInfo;           // 用户信息
  readonly token?: string;       // 访问令牌
  readonly refreshToken?: string; // 刷新令牌
}
```

## 枚举类型

### AppSource - 应用来源
```typescript
enum AppSource {
  Market = "Market",    // 从市场安装
  Manual = "Manual"     // 手动输入
}
```

### AppAction - 应用动作
```typescript
enum AppAction {
  App = "App",           // 应用模式加载
  MenuApp = "MenuApp",   // 托管应用模式加载
  Link = "Link",         // 链接方式打开
  Iframe = "Iframe"      // Iframe内嵌方式打开
}
```

## 通讯协议

### 请求格式
子应用发送到主应用的请求格式：
```typescript
{
  type: 'API_REQUEST',
  id: number,        // 唯一请求ID，用于匹配响应
  method: string,    // 方法名称
  params?: any       // 请求参数（可选）
}
```

### 响应格式
主应用返回给子应用的响应格式：
```typescript
{
  type: 'API_RESPONSE',
  id: number,        // 对应的请求ID
  success: boolean,  // 是否成功
  result?: any,      // 成功时的结果
  error?: string     // 失败时的错误信息
}
```

## 依赖要求

### 对等依赖 (Peer Dependencies)
- **Vue**: ^3.5.13 - Vue 3 框架
- **Vue Router**: ^4.5.0 - Vue 路由管理
- **@skyfox2000/fapi**: ^1.1.19 - API请求库
- **@micro-zoe/micro-app**: ^1.0.0-rc.18 - 微前端框架

## 构建配置

该库使用 Vite 进行构建，支持：
- **TypeScript**: 完整的类型支持
- **ES Module**: 现代化的模块格式
- **类型声明**: 自动生成 .d.ts 文件
- **外部化依赖**: 避免重复打包核心依赖

## 使用场景

### 1. 微前端子应用完整初始化
```typescript
import { 
  isMicroApp, 
  initEnv, 
  initMicroBaseLog,
  initMainAppData,
  initMicroAppProxy,
  initModuleLoader,
  mainAppApis
} from '@skyfox2000/microbase';

// 1. 初始化环境变量
initEnv(import.meta.env);

// 2. 初始化日志（可选）
initMicroBaseLog(true);

// 3. 检测微应用环境并初始化通讯
if (isMicroApp()) {
  // 初始化主应用数据
  initMainAppData();
  
  // 初始化通讯层（数据监听 + 请求代理）
  initMicroAppProxy();
  
  // 初始化模块加载器
  initModuleLoader(import.meta.glob('./views/**/*.vue', { eager: false }));
}

// 4. 使用API
async function example() {
  const userInfo = await mainAppApis.getUserInfo();
  const appInfo = await mainAppApis.getAppInfo();
}
```

### 2. 独立应用
```typescript
// 在独立应用中也可以使用类型定义
import type { AppInfo, UserInfo } from '@skyfox2000/microbase';

const appConfig: AppInfo = {
  Id: 'app-001',
  Name: '我的应用',
  AppCode: 'my-app',
  // ... 其他配置
};
```

## 版本历史

- **v1.3.0**: 统一通讯方式为 forceDispatch + addDataListener
- **v1.2.1**: 完善的微前端通信和类型定义
- **v1.1.x**: 增加模块加载功能
- **v1.0.x**: 初始版本，基础类型定义

## 注意事项

1. **依赖管理**: 确保项目中已安装所有对等依赖
2. **环境检测**: 在使用微前端功能前，先进行环境检测
3. **类型安全**: 充分利用 TypeScript 类型检查，避免运行时错误
4. **版本兼容**: 注意与其他 @skyfox2000 系列库的版本兼容性
5. **异步调用**: 所有 mainAppApis 方法返回 Promise，需要使用 await 或 .then()

## 技术支持

- **仓库地址**: GitHub - @skyfox2000/microbase
- **问题反馈**: 通过 GitHub Issues 提交问题
- **文档更新**: 随版本更新同步维护

---

*该库是微前端生态系统的核心基础库，为构建大型企业级微前端应用提供坚实的技术基础。*