@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 { axiosBrowser } from '@shencom/request';
// import { axiosUniapp } from '@shencom/request';
import { init } from '@shencom/api';

const url = 'xxxx';

init(http, url);
```

### 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] 使用 refreshToken 续期 token: `ApiRefreshToken`;

  - `token` 8 小时有效期
  - `refreshToken` 30 天有效期

- [ ] 更新系统用户信息
- [ ] 注册用户
- [ ] 用户名+密码登录:
- [x] 手机号+密码登录: `ApiPhoneAndPasswordLogin`;
- [ ] 手机号+短信登录:
- [ ] 发送短信:

### uaa-wechat

- [x] 微信小程序登录: `ApiWechatMiniLogin`;
- 小程序手机号登录,并绑定手机号到系统用户（创建系统用户）
- [x] 绑定微信用户登录: `BaseWechatMiniBindPhone`;
- [ ] 退出登录 (解除微信绑定)
- [ ] 微信公众号授权登录
- [ ] 更新微信用户信息
- [ ] 通过 openid 获取用户信息
- [ ] 判断是否关注公众号

### wechat

- [x] 获取公众号 JSSDK 配置: `ApiWechatGetConfig`

### file

- [x] oss 签名: `ApiFileOssSign`
- [x] 将 oss 文件信息更新到数据库: `ApiFileUpdate`
- [x] 服务器文件上传: `ApiFileUpload`
- [x] 获取文件信息: `ApiFileShow`
- [ ] 单个文件上传
- [ ] 文件下载
- [ ] 检查图片是否含有违法违规或政治敏感内容
- [ ] 私有文件下载
- [ ] 私有上传指定 url 的文件
- [ ] 私有文件上传
- [ ] 私有 oss 签名
- [ ] 获取私有临时文件访问链接

### gis

- [x] 创建点位: `ApiGisCreate`;
- [x] 获取点位: `ApiGisShow`;
- [ ] 更新点位
- [ ] 创建范围
- [ ] 更新范围
- [ ] 获取范围

### cms

- [x] 获取栏目: `ApiCMSCategoryTree`;
- [x] 获取内容列表: `ApiCMSArticlesIndex`;
- [x] 获取内容: `ApiCMSArticlesShow`;

### AMap

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

### QQMap

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

## Helpers

**ApiQueryHandler**

- 说明: 查询参数生成格式方法（已废弃，建议使用 ApiQueryItemConstruct 和 ApiQueryConstruct 代替）
- 类型: 
  ```typescript
  function ApiQueryHandler(
    val: string | number | null,
    prop: string,
    operate?: OperateType | Operate,
    lr?: QueryLr
  ): SC.API.IndexQuery;
  
  function ApiQueryHandler(
    params: [string | number | null, string, (OperateType | Operate)?, QueryLr?][]
  ): 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?: SortType): IIndexSorts;
function ApiSortsConstruct(params: [string, SortType?][]): IIndexSorts;
```

**参数:**

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

**返回值:**

返回 IIndexSorts 类型的排序参数对象数组,每个对象包含:
- 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: { orderField: string, orderType: string }): Record<string, string>;
function ApiSortsDestructure(sorts: Array<{ orderField: string, orderType: string }>): Record<string, string>;
```

**参数:**

- `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: IIndexSorts, deleteProps: string | string[]): IIndexSorts | null;
```

**参数:**

- `sorts`: IIndexSorts - 排序条件数组
- `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?: OperateEnum,
  lr?: LrEnum
): 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(
  val: string | number | null | undefined,
  prop: string,
  operate?: OperateEnum,
  lr?: LrEnum
): SC.API.Query[];
function ApiQueryConstruct(
  params: [string | number | null | undefined, string, OperateEnum?, LrEnum?][]
): 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(
  query: SC.API.Query[],
  insertQuery: SC.API.Query | SC.API.Query[]
): SC.API.Query[];
```

**参数:**

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

**返回值:**

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

**示例:**

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

// 向查询条件中插入多个条件
const query = [{ 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(query, 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 }
// ]
```