@shencom/api/README.md

shencom api group

# `@shencom/api`

> 描述....

## install

```sh
pnpm add @shencom/request @shencom/api

# or

yarn add @shencom/request @shencom/api
```

## Usage

### Init

```ts
import { http } from '@shencom/request';
// import { http } from '@shencom/request';
import { init } from '@shencom/api';

const url = 'xxxx';

init(http, url);
```

### Types

如果存在 SC.API 类型问题，在 tsconfig.json 中添加以下配置:
```json
{
  "compilerOptions": {
    "types": ["@shencom/api"]
  }
}
```

### Basic Usage

```ts
import { ApiGisShow } from '@shencom/api';

function getGisShow() {
  const { data } = await ApiGisShow({ ids: ['xxx'] });
  // console.log(data);
}
```

## API

### uaa

- [x] 获取 sccode: `ApiGetScCode`;
- [x] sccode 登录: `ApiScCodeLogin`;
- [x] 手机号 + 密码登录: `ApiPhoneAndPasswordLogin`;
- [x] 获取跨租户授权签名: `ApiScOAuthSecuser`
- [x] 跨租户授权登录: `ApiScOAuthToken`
- [x] refreshToken续期token: `ApiRefreshToken`
- [x] 租户端-手机号/用户名 + 密码 + 验证码/图形验证码: `ApiPhoneOrUsernameAndPasswordAndCodeLogin`
- [x] 平台端-手机号/用户名 + 密码 + 验证码/图形验证码: `ApiPhoneOrUsernameAndPasswordAndCodeLoginPlatform`
- [x] 手机号/用户名 + 密码登录: `ApiPhoneOrUsernameAndPasswordLogin`
- [x] 租户端-更新系统用户信息: `ApiSysUpdateInfo`
- [x] 平台端-更新系统用户信息: `ApiSysUpdateInfoPlatform`
- [x] 手机号验证码登录-未注册的手机号，会自动注册: `ApiPhoneAndCodeLoginOrRegister`
- [x] 手机号验证码登录: `ApiPhoneAndCodeLogin`
- [x] 获取明文的当前系统用户信息: `ApiGetPlaintextUserInfo`
- [x] 租户端-系统用户自行更改密码: `ApiUserSysUpdate`
- [x] 平台端-系统用户自行更改密码: `ApiUserSysUpdatePlatform`
- [x] 租户端-通过手机号或用户名找回密码: `ApiResetPwd`
- [x] 平台端-通过手机号或用户名找回密码: `ApiResetPwdPlatform`
- [x] 是否需要修改密码: `ApiNeedChangePwd`
- [x] 判断当前租户发送短信是否需要图形验证: `ApiNeedGraphic`
- [x] 获取图形验证码: `ApiValidateImage`
- [x] 用户登出: `ApiLogOut`
- [x] 罗湖一级平台登录: `ApiIlhOauthLogin`

### uaa-wechat

- [x] 微信小程序手机号绑定并登录: `ApiWechatMiniBindPhone`;
- [x] 微信小程序登录: `ApiWechatMiniLogin`;
- [x] 微信二维码登录: `ApiWechatCodeLogin`
- [x] 更新微信用户信息: `ApiWechatUpdateInfo`;
- [x] 退出微信登录状态: `ApiWechatLogout`;
- [x] 绑定微信用户登录: `ApiWechatCodeBindPhone`;
- [x] 通过 code 获取用户信息: `ApiWechatCodeAuth`;
- [x] 获取授权跳转链接: `ApiWechatAuthUrl`;
- [x] 获取微信用户绑定过的账号列表: `ApiWechatUserRecords`;
- [x] 平台端-通过手机号绑定微信扫码登录: `ApiWechatBindPhonePlatform`;
- [x] 租户端-通过手机号绑定微信扫码登录: `ApiWechatBindPhone`;

### wechat

- [x] 获取公众号JSSDK配置: `ApiWechatGetConfig`;
- [x] 获取微信登录二维码: `ApiWechatGetQrcode`;

### file

- [x] 获取文件信息: `ApiFileShow`;
- [x] 获取oss直传所需Policy和签名: `ApiFileOssSign`
- [x] 获取oss直传所需Policy和签名 V2: `ApiFileOssSignV2`
- [x] 批量获取oss直传所需Policy和签名 V2: `ApiFileOssBatchSignV2`
- [x] oss签名上传文件: `ApiFileOssUpload`
- [x] oss签名上传文件 V2: `ApiFileOssUploadV2`
- [x] 将 oss 文件信息更新到数据库: `ApiFileUpdate`
- [x] 服务器上传: `ApiFileUpload`
- [x] 获取临时sts-token【全功能】: `ApiFileStsToken`
- [x] 获取私有临时文件访问链接: `ApiFilePresigned`
- [x] 判断是否重复照片: `ApiFileExist`
- [x] 判断重复照片: `ApiFileRepeat`

### gis

- [x] 创建点位: `ApiGisCreate`;
- [x] 获取点位: `ApiGisShow`;
- [x] 根据经纬度获取区域: `ApiFindRegionByLngLat`

### cms

- [x] 获取栏目 tree: `ApiCMSCategoryTree`;
- [x] 获取栏目 index: `ApiCMSCategoryIndex`;
- [x] 获取内容列表: `ApiCMSArticlesIndex`;
- [x] 获取文章内容: `ApiCMSArticlesShow`;

### AMap

- [x] 高德-地理编码: `ApiAMapGeocodeGeo`;
- [x] 高德-逆地理编码: `ApiAMapGeocodeRegeo`;
- [x] 高德-天气查询: `ApiAMapWeather`;
- [x] 高德-输入提示: `ApiAMapInputtips`;
- [x] 高德-IP定位: `ApiAMapIP`;

### QQMap

- [x] 腾讯-地理编码: `ApiQQMapGeocodeGeo`;
- [x] 腾讯-逆地理编码: `ApiQQMapGeocodeRegeo`;
- [x] 腾讯-IP定位: `ApiQQMapIP`;

### sms

- [x] 租户端-发送短信: `ApiSmsTenants`;
- [x] 平台端-发送短信: `ApiSmsPlatform`;
- [x] 发送未绑定用户短信: `ApiSmsUnbound`;

### yzy

- [x] 粤政易-获取粤政易授权链接: `ApiYzyGetAuthUrl`;
- [x] 粤政易-通过授权 code 获取 access_token: `ApiYzyCodeAuth`;
- [x] 粤政易-根据access_token验证登陆状态是否有效: `ApiYzyAuthVerify`;
- [x] 粤政易-通过refresh_token置换新的access_toke: `ApiYzyRefreshToken`;
- [x] 粤政易-通过access_token获取用户信息: `ApiYzyLogin`;
- [x] 粤政易-退出登录: `ApiYzyLogout`;
- [x] 粤政易-获取粤政易JSSDK配置: `ApiYyzGetSDKConfig`;

## Helpers

**ApiQueryHandler**

- 说明: 查询参数生成格式方法（已废弃，建议使用 ApiQueryItemConstruct 和 ApiQueryConstruct 代替）
- 类型: 
  ```typescript
  function ApiQueryHandler(
    val: QueryValue,
    prop: string,
    operate?: OperateType | SC.API.Operate,
    lr?: SC.API.Lr,
  ): SC.API.IndexQuery;
  
  function ApiQueryHandler(
    params: [QueryValue, string, (OperateType | SC.API.Operate)?, SC.API.Lr?][],
  ): SC.API.IndexQuery;
  ```
- 参数:
  - `val`: string | number | null - 查询的值
  - `prop`: string - 后端字段
  - `operate?`: OperateType | Operate - 筛选条件 (默认: 'string')
  - `lr?`: LrEnum - 逻辑关系(LrEnum.AND 或 LrEnum.OR)
  - `params`: [val, prop, operate?, lr?][] - 查询参数数组
- 返回: `SC.API.IndexQuery` - 包含exps数组的查询索引对象
- 示例:
  ```typescript
  // 基本用法
  ApiQueryHandler('1', 'active');
  // 返回: [{ exps: [{ value: '1', prop: 'active', operate: 'LIKE' }] }]
  
  // 使用特定操作类型
  ApiQueryHandler('2022-01-01', 'createdAt', 'rangeDateTime');
  // 返回: [{ exps: [{ value: '2022-01-01', prop: 'createdAt', operate: 'BTW' }] }]
  
  // 使用枚举值
  ApiQueryHandler(100, 'age', OperateEnum.EQ);
  // 返回: [{ exps: [{ value: 100, prop: 'age', operate: 'EQ' }] }]
  
  // 多条件查询
  ApiQueryHandler([
    [100, 'age', OperateEnum.EQ],
    ['张三', 'name', OperateEnum.LIKE, LrEnum.AND]
  ]);
  // 返回: [{ 
  //   exps: [
  //     { value: 100, prop: 'age', operate: 'EQ' },
  //     { value: '张三', prop: 'name', operate: 'LIKE', lr: 'and' }
  //   ] 
  // }]
  ```

**Jsencrypt**

- 说明: 密码加密
- 类型: `(pwd: string) => string`
- 参数:
  - `pwd`: 明文密码
- 返回: `string`
- 示例:
  ```ts
  const password = Jsencrypt('sc123456');
  ```

## API 工具函数

### sorts

排序参数生成工具函数,用于生成统一的排序参数格式。

#### ApiSortsConstruct

生成排序参数对象。

**函数签名:**

```typescript
function ApiSortsConstruct(prop: string, type?: SC.API.SortType): SC.API.IndexSorts;
function ApiSortsConstruct(params: [string, (SC.API.SortType | string)?][]): SC.API.IndexSorts;
```

**参数:**

- `prop`: string - 排序字段名
- `type`: SortType - 可选的排序类型,可选值为 'ASC' 或 'DESC',默认为 'DESC'
- `params`: [string, SortType?][] - 排序参数数组,每个元素为 [字段名, 排序类型] 的元组

**返回值:**

返回 SC.API.IndexSorts 类型的排序参数对象数组,每个对象包含:
- orderField: 排序字段名
- orderType: 排序类型('ASC' 或 'DESC')

**示例:**

```typescript
// 单个字段排序
ApiSortsConstruct('createTime')
// 返回: [{ orderField: 'createTime', orderType: 'DESC' }]

// 指定排序类型
ApiSortsConstruct('createTime', 'ASC')
// 返回: [{ orderField: 'createTime', orderType: 'ASC' }]

// 多字段排序
ApiSortsConstruct([
  ['createTime', 'DESC'],
  ['updateTime', 'ASC']
])
// 返回: [
//   { orderField: 'createTime', orderType: 'DESC' },
//   { orderField: 'updateTime', orderType: 'ASC' }
// ]

// 多字段排序(使用默认排序类型)
ApiSortsConstruct([
  ['createTime'],
  ['updateTime']
])
// 返回: [
//   { orderField: 'createTime', orderType: 'DESC' },
//   { orderField: 'updateTime', orderType: 'DESC' }
// ]
```

#### ApiSortsDestructure

将排序对象转换为键值对格式。

**函数签名:**

```typescript
function ApiSortsDestructure(sort: SC.API.Sorts): Record<string, SC.API.SortType>;
function ApiSortsDestructure(sorts: SC.API.Sorts[]): Record<string, SC.API.SortType>;
```

**参数:**

- `sort`: { orderField: string, orderType: string } - 单个排序对象
- `sorts`: Array<{ orderField: string, orderType: string }> - 排序对象数组

**返回值:**

返回 Record<string, string> 类型的键值对对象，键为排序字段名，值为排序类型。

**示例:**

```typescript
// 转换单个排序对象
ApiSortsDestructure({ orderField: 'createTime', orderType: 'DESC' })
// 返回: { "createTime": "DESC" }

// 转换排序对象数组
ApiSortsDestructure([
  { orderField: 'createTime', orderType: 'DESC' },
  { orderField: 'updateTime', orderType: 'ASC' }
])
// 返回: { "createTime": "DESC", "updateTime": "ASC" }

// 如果排序类型为空，则使用默认值 'DESC'
ApiSortsDestructure({ orderField: 'createTime', orderType: '' })
// 返回: { "createTime": "DESC" }
```

#### ApiSortsDelete

从排序数组中删除指定字段的排序条件。

**函数签名:**

```typescript
function ApiSortsDelete(
  sorts: SC.API.IndexSorts,
  deleteProps: string | string[],
): SC.API.IndexSorts | null;
```

**参数:**

- `sorts`: SC.API.IndexSorts - 排序条件数组
- `deleteProps`: string | string[] - 要删除的字段名(单个字符串或字符串数组)

**返回值:**

返回处理后的排序条件数组，如果结果为空数组则返回null。

**示例:**

```typescript
// 删除单个字段的排序
const sorts = [
  { orderField: 'createTime', orderType: 'DESC' }, 
  { orderField: 'updateTime', orderType: 'ASC' }
];
ApiSortsDelete(sorts, 'createTime'); 
// 返回: [{ orderField: 'updateTime', orderType: 'ASC' }]

// 删除多个字段的排序
const sorts = [
  { orderField: 'createTime', orderType: 'DESC' }, 
  { orderField: 'updateTime', orderType: 'ASC' },
  { orderField: 'name', orderType: 'ASC' }
];
ApiSortsDelete(sorts, ['createTime', 'name']); 
// 返回: [{ orderField: 'updateTime', orderType: 'ASC' }]

// 当结果为空数组时返回null
const sorts = [{ orderField: 'createTime', orderType: 'DESC' }];
ApiSortsDelete(sorts, 'createTime'); 
// 返回: null
```

### query

查询参数生成工具函数，用于生成统一的查询参数格式。

#### ApiQueryItemConstruct

创建单个查询条件表达式。

**函数签名:**

```typescript
function ApiQueryItemConstruct(
  val: string | number | null | undefined,
  prop: string,
  operate?: SC.API.Operate,
  lr?: SC.API.Lr
): SC.API.Query | null;
```

**参数:**

- `val`: string | number | null | undefined - 查询的值
- `prop`: string - 查询的字段名
- `operate`: OperateEnum - 可选的操作类型，默认为 OperateEnum.LIKE
- `lr`: LrEnum - 可选的逻辑关系

**返回值:**

返回 SC.API.Query 类型的查询条件对象，包含:
- value: 查询的值
- prop: 查询的字段名
- operate: 操作类型
- lr: 逻辑关系

如果值为null、undefined或空字符串，则返回null。

**示例:**

```typescript
// 创建单个查询条件
ApiQueryItemConstruct('张三', 'name')
// 返回: { value: '张三', prop: 'name', operate: OperateEnum.LIKE }

// 指定操作类型
ApiQueryItemConstruct(100, 'age', OperateEnum.EQ)
// 返回: { value: 100, prop: 'age', operate: OperateEnum.EQ }

// 日期范围查询
ApiQueryItemConstruct('2022-01-01', 'createTime', OperateEnum.BTW)
// 返回: { value: '2022-01-01', prop: 'createTime', operate: OperateEnum.BTW }
```

#### ApiQueryConstruct

创建查询条件表达式数组。

**函数签名:**

```typescript
function ApiQueryConstruct(...params: ApiQueryConstructParams): SC.API.Query[];
function ApiQueryConstruct(params: ApiQueryConstructParams[]): SC.API.Query[];
```

**参数:**

- `val`: string | number | null | undefined - 查询的值
- `prop`: string - 查询的字段名
- `operate`: OperateEnum - 可选的操作类型，默认为 OperateEnum.LIKE
- `lr`: LrEnum - 可选的逻辑关系
- `params`: [string | number | null | undefined, string, OperateEnum?, LrEnum?][] - 查询参数数组

**返回值:**

返回 SC.API.Query[] 类型的查询条件数组，空值会被过滤掉。

**示例:**

```typescript
// 单个查询条件
ApiQueryConstruct('张三', 'name')
// 返回: [{ value: '张三', prop: 'name', operate: OperateEnum.LIKE }]

// 多个查询条件
ApiQueryConstruct([
  [100, 'age', OperateEnum.EQ],
  ['张三', 'name', OperateEnum.LIKE, LrEnum.AND]
])
// 返回: [
//   { value: 100, prop: 'age', operate: OperateEnum.EQ },
//   { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }
// ]

// 过滤空值
ApiQueryConstruct([
  [100, 'age', OperateEnum.EQ],
  [null, 'status'],
  ['张三', 'name', OperateEnum.LIKE, LrEnum.AND]
])
// 返回: [
//   { value: 100, prop: 'age', operate: OperateEnum.EQ },
//   { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }
// ]
```

#### ApiQueryDestructure

将查询条件转换为键值对格式。

**函数签名:**

```typescript
function ApiQueryDestructure(query: SC.API.Query): Record<string, any>;
function ApiQueryDestructure(queries: SC.API.Query[]): Record<string, any>;
```

**参数:**

- `query`: SC.API.Query - 单个查询条件
- `queries`: SC.API.Query[] - 查询条件数组

**返回值:**

返回 Record<string, any> 类型的键值对对象，键为查询字段名，值为查询的值。

**示例:**

```typescript
// 转换单个查询条件
ApiQueryDestructure({ value: '张三', prop: 'name', operate: OperateEnum.LIKE })
// 返回: { "name": "张三" }

// 转换查询条件数组
ApiQueryDestructure([
  { value: 100, prop: 'age', operate: OperateEnum.EQ },
  { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }
])
// 返回: { "age": 100, "name": "张三" }
```

#### ApiQueryInsert

向查询条件数组中插入查询条件。

**函数签名:**

```typescript
function ApiQueryInsert(
  target: SC.API.Query[],
  source: SC.API.Query | SC.API.Query[]
): SC.API.Query[];
```

**参数:**

- `target`: SC.API.Query[] - 查询条件数组
- `source`: SC.API.Query | SC.API.Query[] - 要插入的查询条件

**返回值:**

返回插入后的查询条件数组。

**示例:**

```typescript
// 向查询条件中插入单个条件
const target = [{ value: 100, prop: 'age', operate: OperateEnum.EQ }];
const newQuery = { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND };
ApiQueryInsert(target, newQuery)
// 返回: [
//   { value: 100, prop: 'age', operate: OperateEnum.EQ },
//   { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }
// ]

// 向查询条件中插入多个条件
const target = [{ value: 100, prop: 'age', operate: OperateEnum.EQ }];
const newQueries = [
  { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND },
  { value: 1, prop: 'gender', operate: OperateEnum.EQ, lr: LrEnum.AND }
];
ApiQueryInsert(target, newQueries)
// 返回: [
//   { value: 100, prop: 'age', operate: OperateEnum.EQ },
//   { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND },
//   { value: 1, prop: 'gender', operate: OperateEnum.EQ, lr: LrEnum.AND }
// ]
```

#### ApiQueryDelete

从查询条件数组中删除指定字段的查询条件。

**函数签名:**

```typescript
function ApiQueryDelete(
  query: SC.API.Query[],
  deleteProps: string | string[]
): SC.API.Query[] | null;
```

**参数:**

- `query`: SC.API.Query[] - 查询条件数组
- `deleteProps`: string | string[] - 要删除的字段名

**返回值:**

返回删除后的查询条件数组，如果结果为空则返回null。

**示例:**

```typescript
// 删除单个字段的查询条件
const query = [
  { value: 100, prop: 'age', operate: OperateEnum.EQ },
  { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }
];
ApiQueryDelete(query, 'age')
// 返回: [{ value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }]

// 删除多个字段的查询条件
const query = [
  { value: 100, prop: 'age', operate: OperateEnum.EQ },
  { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND },
  { value: 1, prop: 'gender', operate: OperateEnum.EQ, lr: LrEnum.AND }
];
ApiQueryDelete(query, ['age', 'gender'])
// 返回: [{ value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }]

// 当结果为空数组时返回null
const query = [{ value: 100, prop: 'age', operate: OperateEnum.EQ }];
ApiQueryDelete(query, 'age')
// 返回: null
```

### 操作类型枚举

**OperateEnum**

查询操作类型枚举，提供了所有可用的查询操作符。

```typescript
enum OperateEnum {
  /** 等于 */
  EQ = 'EQ',
  /** 小于 */
  LT = 'LT',
  /** 大于 */
  GT = 'GT',
  /** 小于等于 */
  LTE = 'LTE',
  /** 大于等于 */
  GTE = 'GTE',
  /** 不等于 */
  NEQ = 'NEQ',
  /** 包含 */
  IN = 'IN',
  /** 非空 */
  NN = 'NN',
  /** 为空 */
  NULL = 'NULL',
  /** 区间 */
  BTW = 'BTW',
  /** 模糊匹配 */
  LIKE = 'LIKE',
  /** 左模糊匹配 */
  LL = 'LL',
  /** 右模糊匹配 */
  RL = 'RL'
}
```

**使用示例:**

```typescript
import { OperateEnum, ApiQueryItemConstruct } from '@shencom/api';

// 创建一个等于查询条件
const equalsQuery = ApiQueryItemConstruct(100, 'age', OperateEnum.EQ);
// 返回: { value: 100, prop: 'age', operate: 'EQ' }

// 创建一个模糊匹配查询条件
const likeQuery = ApiQueryItemConstruct('张三', 'name', OperateEnum.LIKE);
// 返回: { value: '张三', prop: 'name', operate: 'LIKE' }

// 创建一个区间查询条件
const betweenQuery = ApiQueryItemConstruct('2022-01-01', 'createTime', OperateEnum.BTW);
// 返回: { value: '2022-01-01', prop: 'createTime', operate: 'BTW' }
```

**LrEnum**

查询逻辑关系枚举，用于定义多个查询条件之间的逻辑关系。

```typescript
enum LrEnum {
  /** 并且 */
  AND = 'and',
  /** 或者 */
  OR = 'or'
}
```

**使用示例:**

```typescript
import { OperateEnum, LrEnum, ApiQueryConstruct } from '@shencom/api';

// 创建多个条件的查询数组，使用AND逻辑关系
const query = ApiQueryConstruct([
  [100, 'age', OperateEnum.EQ],
  ['张三', 'name', OperateEnum.LIKE, LrEnum.AND] // 使用AND关系
]);
// 返回: [
//   { value: 100, prop: 'age', operate: OperateEnum.EQ },
//   { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.AND }
// ]

// 使用OR逻辑关系
const orQuery = ApiQueryConstruct([
  [100, 'age', OperateEnum.EQ],
  ['张三', 'name', OperateEnum.LIKE, LrEnum.OR] // 使用OR关系
]);
// 返回: [
//   { value: 100, prop: 'age', operate: OperateEnum.EQ },
//   { value: '张三', prop: 'name', operate: OperateEnum.LIKE, lr: LrEnum.OR }
// ]
```


**SortTypeEnum**

排序类型枚举，用于定义排序类型。

```typescript
enum SortTypeEnum {
  /** 升序 */
  ASC = 'ASC',
  /** 降序 */
  DESC = 'DESC'
}
```

**使用示例:**

```typescript
import { SortTypeEnum, ApiSortsConstruct } from '@shencom/api';

// 创建一个升序排序
const ascSort = ApiSortsConstruct('createTime', SortTypeEnum.ASC);
// 返回: [{ orderField: 'createTime', orderType: 'ASC' }]
```