# @kasite/uni-app-base

## 项目简介

`@kasite/uni-app-base` 是智医科技（Kasite）公司开发的 uni-app 基础包，为医院信息化系统提供统一的基础功能模块。该包封装了小程序登录、网络请求、配置管理、工具函数等核心功能，支持微信小程序和公众号两种平台。

## 主要特性

- 🔐 **统一登录管理** - 支持微信小程序和公众号登录，自动处理 token 过期和重新登录
- 🌐 **网络请求封装** - 统一的 HTTP 请求处理，支持加密传输和自动重试机制
- ⚙️ **配置管理系统** - 灵活的前端配置管理，支持多院区、多业务场景配置
- 🛠️ **工具函数库** - 丰富的通用工具函数，包括加密解密、数据验证等
- 📱 **多平台支持** - 同时支持微信小程序和公众号平台
- 🔒 **安全加密** - 内置 DES 加密算法，保障数据传输安全

## 安装

```bash
npm install @kasite/uni-app-base
```

## 快速开始

### 导入基础包

```javascript
import { 
  request, 
  useSmallProgramLogin, 
  useAppStatus,
  useSetFrontEndConfig,
  useGetUpdateManager,
  usePreserMember,
  frontEndConfig,
  common 
} from '@kasite/uni-app-base';
```

### Hook 使用示例

```javascript
// 应用启动时的初始化流程
export default {
  async onLaunch() {
    // 1. 设置前端配置
    await useSetFrontEndConfig();
    
    // 2. 检查应用状态
    await useAppStatus();
    
    // 3. 检查版本更新
    await useGetUpdateManager();
    
    // 4. 获取就诊人信息
    await usePreserMember();
    
    // 5. 小程序登录
    await useSmallProgramLogin(getApp());
  }
}

// 获取域名信息
const domain = useDomain();

// 设置菜单
const menuList = await useSetMenuList(defaultMenu);

// 设置表单配置
await useSetFrontEndForm();

// 获取系统页面列表
await useGetSysAppPageList();
```

## 📚 API 文档

### 🌐 网络请求模块

#### `request.doPost(url, data, options?, complete?)`
发起 HTTP POST 请求，支持自动重试和加密传输

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `url` | `string` | ✅ | 请求地址 |
| `data` | `object` | ✅ | 请求数据 |
| `options` | `object` | ❌ | 请求选项 |
| `complete` | `function` | ❌ | 完成回调函数 |

**Options 选项：**
```typescript
interface RequestOptions {
  showLoading?: boolean;    // 是否显示加载提示，默认 true
  timeout?: number;         // 超时时间（毫秒）
  responseType?: string;    // 响应类型
  onChunkReceived?: function; // 分块传输监听
}
```

**使用示例：**
```javascript
// 基础 POST 请求
const response = await request.doPost('/api/login', {
  username: 'user',
  password: 'pass'
});

// 带选项的请求
const response = await request.doPost('/api/data', data, {
  showLoading: false,
  timeout: 30000
});
```

---

#### `request.doGet(url, data, options?)`
发起 HTTP GET 请求

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `url` | `string` | ✅ | 请求地址 |
| `data` | `object` | ✅ | 请求参数 |
| `options` | `object` | ❌ | 请求选项 |

**使用示例：**
```javascript
// 基础 GET 请求
const response = await request.doGet('/api/user', {
  userId: '123'
});
```

## 🎣 Hook 使用指南

Hook 是本基础包的核心功能模块，提供了丰富的业务逻辑封装。

### 🔐 登录管理

#### `useSmallProgramLogin(app)`
小程序登录，支持微信小程序和公众号平台

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `app` | `App.AppInstance` | ✅ | 应用实例对象 |

**返回值：**
- `Promise<boolean>` - 登录结果

**功能特性：**
- ✅ 自动处理 token 过期
- ✅ 支持重新登录机制
- ✅ 防并发登录调用
- ✅ 自动缓存登录信息

**使用示例：**
```javascript
// 小程序登录
const loginResult = await useSmallProgramLogin(getApp());
if (loginResult) {
  console.log('登录成功');
}
```

### 🔧 应用状态管理

#### `useAppStatus()`
检查应用状态并进行相应跳转

**功能特性：**
- 🔍 检查应用维护状态
- 🚫 检查应用下线状态  
- 🔄 自动跳转到错误页面

**状态类型：**
- `maintain` - 维护状态，跳转到维护页面
- `offline` - 下线状态，跳转到下线页面

**使用示例：**
```javascript
// 应用启动时检查状态
await useAppStatus();
```

### 🌍 域名管理

#### `useDomain()`
获取当前域名信息，支持KasiteWeb路径处理

**返回值：**
- `string` - 当前域名地址

**使用示例：**
```javascript
const domain = useDomain();
console.log('当前域名:', domain);
```

### ⚙️ 配置管理

#### `useSetFrontEndConfig()`
设置前端配置信息，初始化全局配置数据

**功能特性：**
- 📥 获取前端配置信息
- 🔧 设置全局配置数据
- 🏥 处理院区配置
- ✅ 检查配置完整性

**使用示例：**
```javascript
// 应用启动时设置配置
await useSetFrontEndConfig();
```

#### `useFrontEndConfigVersion()`
获取前端配置版本信息，控制缓存更新策略

**功能特性：**
- 🔄 检查配置版本更新
- 💾 控制缓存更新策略
- 🌐 网络异常处理

**使用示例：**
```javascript
// 检查配置版本
await useFrontEndConfigVersion();
```

### 📄 系统页面管理

#### `useGetSysAppPageList()`
获取系统应用页面列表，转换为页面消息映射

**功能特性：**
- 📋 获取系统页面配置
- 🔄 转换为页面消息映射
- 💾 存储到全局数据

**使用示例：**
```javascript
// 获取系统页面列表
await useGetSysAppPageList();
```

### 🔄 更新管理

#### `useGetUpdateManager()`
检查小程序版本更新，自动处理更新流程

**功能特性：**
- 🔍 检查新版本
- ⬇️ 自动下载更新
- 💬 提示用户重启应用
- ❌ 处理更新失败情况

**更新流程：**
1. 检查版本更新
2. 自动下载新版本
3. 提示用户重启
4. 处理下载失败

**使用示例：**
```javascript
// 检查版本更新
const hasUpdate = await useGetUpdateManager();
```

### 👥 就诊人管理

#### `usePreserMember()`
查询并保存就诊人数据，管理用户就诊信息

**功能特性：**
- 🔍 查询所有就诊人信息
- 💾 保存到全局存储
- 👤 更新当前用户信息
- 🔐 支持加密查询

**使用示例：**
```javascript
// 获取就诊人信息
const memberList = await usePreserMember();
```

### 📝 表单配置管理

#### `useSetFrontEndForm()`
设置前端表单配置，管理动态表单

**功能特性：**
- 📋 获取表单配置信息
- ✅ 验证配置完整性
- 💾 存储表单配置
- 🏥 支持多院区配置

**使用示例：**
```javascript
// 设置表单配置
await useSetFrontEndForm();
```

### 🍔 菜单管理

#### `useSetMenuList(menu)`
设置应用菜单列表，支持线上线下菜单合并

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `menu` | `array` | ✅ | 本地菜单数组 |

**功能特性：**
- 🌐 获取线上菜单配置
- 🔄 合并本地和线上菜单
- 💾 存储菜单配置
- 📱 支持多平台菜单

**使用示例：**
```javascript
// 设置菜单
const defaultMenu = [
  { name: '首页', path: '/pages/home' },
  { name: '预约', path: '/pages/appointment' }
];
const menuList = await useSetMenuList(defaultMenu);
```

## 🛠️ 工具函数库

工具函数库提供了丰富的通用功能，包括UI交互、数据验证、加密解密等。

### UI 交互

#### `common.showLoading(title?)`
显示加载提示，支持防重复显示

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `title` | `string` | ❌ | 加载提示文字 |

#### `common.hideLoading()`
隐藏加载提示，智能处理多接口并发

#### `common.showToast(msg, fn?, duration?)`
显示提示消息

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `msg` | `string` | ✅ | 提示消息内容 |
| `fn` | `function` | ❌ | 回调函数 |
| `duration` | `number` | ❌ | 显示时长（毫秒），默认1500 |

#### `common.showModal(content, callBack?, data?)`
显示模态框

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `content` | `string` | ✅ | 模态框内容 |
| `callBack` | `function` | ❌ | 确认回调函数 |
| `data` | `object` | ❌ | 模态框配置 |

### 数据验证

#### `common.isEmpty(obj)`
判断对象是否为空

**支持类型：**
- `undefined` / `null` / `''`
- `Array` - 检查长度
- `Object` - 检查键数量

#### `common.isNotEmpty(obj)`
判断对象是否不为空（isEmpty的反向）

### 加密解密

#### `common.desEncrypt(message, key)`
DES 加密

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `message` | `string` | ✅ | 待加密内容 |
| `key` | `string` | ✅ | 加密密钥 |

#### `common.desDecrypt(str, key, exportType?)`
DES 解密

| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `str` | `string` | ✅ | 加密字符串 |
| `key` | `string` | ✅ | 解密密钥 |
| `exportType` | `string` | ❌ | 输出方式 |

### 使用示例

```javascript
// UI 交互
common.showLoading('加载中...');
common.showToast('操作成功', () => {
  console.log('提示完成');
});
common.showModal('确定要删除吗？', () => {
  console.log('用户确认删除');
});

// 数据验证
if (common.isNotEmpty(userData)) {
  console.log('用户数据有效');
}

// 加密解密
const encrypted = common.desEncrypt('敏感数据', 'secretKey');
const decrypted = common.desDecrypt(encrypted, 'secretKey');
```

## 配置说明

### 基础配置 (config.ts)

```typescript
export const BASE_URL = 'https://cs001.kasitesoft.com/';  // 接口请求地址
export const IS_ENCRYPT = false;                          // 是否加密
export const TIMEOUT = 60000;                             // 超时时间
```

### 前端配置 (frontEndConfig.ts)

包含以下主要配置：

- **固定配置** (`fixedAppjsGlobalData`): 医院ID、配置密钥等固定信息
- **应用配置** (`appjsGlobalData`): 医院信息、功能开关等可配置项
- **页面配置** (`webUiDiy`): 各业务页面的个性化配置

## 目录结构

```
├── config/                 # 配置文件
│   ├── config.ts          # 基础配置
│   ├── frontEndConfig.ts  # 前端配置
│   └── index.ts           # 配置导出
├── hook/                  # 自定义 Hook
│   ├── use-app-status/    # 应用状态管理
│   ├── use-domain/        # 域名管理
│   ├── use-front-end-config/  # 前端配置管理
│   ├── use-front-end-config-version/  # 前端配置版本管理
│   ├── use-get-sys-app-page-list/  # 系统页面列表管理
│   ├── use-get-update-manager/  # 更新管理
│   ├── use-preser-member/  # 就诊人管理
│   ├── use-set-front-end-form/  # 表单配置管理
│   ├── use-set-menu-list/  # 菜单管理
│   └── use-small-program-login/  # 小程序登录
├── service/               # 服务层
│   ├── base/             # 基础服务
│   ├── request.ts        # 网络请求封装
│   └── handle.js         # 请求处理
├── utils/                 # 工具函数
│   ├── common.ts         # 通用工具
│   ├── crypto-js.min.js  # 加密库
│   └── sseParse.ts       # SSE 解析
└── index.ts              # 主入口文件
```

## 开发指南

### 添加新的 Hook

1. 在 `hook/` 目录下创建新的 Hook 文件夹
2. 实现 Hook 逻辑
3. 在 `hook/index.ts` 中导出

### 添加新的工具函数

1. 在 `utils/common.ts` 中添加函数
2. 确保函数已导出
3. 在 `utils/index.ts` 中导出

### 配置管理

所有配置都集中在 `config/` 目录下，支持：
- 环境变量配置
- 业务功能开关
- 页面个性化配置

## 版本信息

- **当前版本**: 0.0.1
- **包名**: @kasite/uni-app-base
- **发布地址**: http://maven.kasitesoft.com/repository/intelmt-npm-hosted/

## 注意事项

1. **平台兼容性**: 确保在目标平台（微信小程序/公众号）上测试所有功能
2. **配置安全**: 生产环境中请妥善保管 API 密钥和配置信息
3. **网络请求**: 所有网络请求都会自动处理 token 过期和重新登录
4. **加密传输**: 根据配置决定是否启用请求加密

## 技术支持

如有问题或建议，请联系智医科技开发团队。

## 许可证

本项目为私有包，仅供智医科技内部使用。