# KWC Shared Utils 使用文档

## 概述
`@kdcloudjs/kwc-shared-utils` 是一个为 KWC 项目提供的共享工具库，包含：
- 客户端环境检测（`client`）
- 平台资源加载器（`platformResourceLoader`）
- OpenAPI 适配器与认证（`openApiAdapter`）
- 组件间消息中心（`messageService`）
- 其他实用模块（如 `kingdeeDataService`、`sendBosPlatformEvent`）

## 安装
```bash
npm install @kdcloudjs/kwc-shared-utils
```

## 导入
支持 ES Module 和 CommonJS：
```javascript
// ES Module
import { client, platformResourceLoader, openApiAdapter, messageService } from '@kdcloudjs/kwc-shared-utils'

// CommonJS
const { client, platformResourceLoader, openApiAdapter, messageService } = require('@kdcloudjs/kwc-shared-utils')
```

## 消息中心（发布-订阅）
用于 React 组件与 Web Components 之间的解耦通信，支持本地与跨标签广播：
```javascript
import { messageService } from '@kdcloudjs/kwc-shared-utils'

// 在组件实例上订阅（component 可为 React 组件实例或自定义元素实例）
const off = messageService.subscribe(component, 'user:login', (payload, { fromRemote }) => {
  console.log('用户登录:', payload, '是否远程广播:', fromRemote)
})

// 发布消息（默认同时本地触发并跨标签广播）
messageService.publish('user:login', { id: 'u001', name: 'Alice' })

// 仅本地触发（不广播）
messageService.publish('user:login', { id: 'u001' }, { global: false })

// 取消订阅
off()

// 也可整体取消某组件在某事件上的订阅
messageService.unsubscribe(component, 'user:login')
```
特性：
- 使用 `BroadcastChannel`（自动降级到 `postMessage`）实现跨标签页/iframe 通信
- 每个组件实例的订阅以 `WeakMap` 管理，自动清理泄漏
- 错误隔离，单个订阅错误不会影响其他订阅者

## OpenAPI 适配器与认证
初始化认证并调用接口：
```javascript
import { openApiAdapter } from '@kdcloudjs/kwc-shared-utils'

await openApiAdapter.initializeAuth({
  endpoint: '/kapi/oauth2/getToken',
  method: 'POST',
  bodyParams: { /* appId、appSecret、nonce 等 */ },
  // 仅内存存储（不持久化），无需也不接受其他存储策略
})

// 发起请求（示例：OpenAPI 服务调用）
const result = await openApiAdapter.doFetch({
  endpointConfig: {
    isv: 'kd', app: 'myapp', form: 'myform', serviceName: 'myservice', version: 'v2'
  },
  params: { query: 'test' }
})
```

### Token 存储安全
- 仅使用 `memory`（内存存储，不持久化），不支持 `session` 与 `local`，以最大限度降低 XSS 风险。
- 推荐由服务端设置 `HttpOnly`、`Secure`、`SameSite` 的 Cookie，通过接口换取临时访问令牌；前端不持久化 token。

## 平台资源加载器
动态加载外部脚本与样式：
```javascript
import { platformResourceLoader } from '@kdcloudjs/kwc-shared-utils'

await platformResourceLoader.loadScript(document.head, 'https://example.com/script.js')
await platformResourceLoader.loadStyle(document.head, 'https://example.com/style.css')
```
特性：
- URL 级缓存，避免重复加载
- 支持 Promise 与回调

## 客户端检测
检测应用、浏览器与设备：
```javascript
import { client } from '@kdcloudjs/kwc-shared-utils'

const appName = client.getAppName() // 'yunzhijia' | 'weixin' | 'dingding' 等
const isMobile = client.isMobile()
const browser = client.getBrowserName() // 'chrome' | 'edge' | 'safari' 等
```

## 构建与发布
使用 Rollup 构建：
```bash
npm run build
```
输出 `dist/`，含 CJS 与 ESM 两种格式，按模块分别打包并压缩。

## 版本
- 当前版本：1.0.0
- 包名：`@kdcloudjs/kwc-shared-utils`