@shencom/api

> 描述....

install

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

or

yarn add @shencom/request @shencom/api
`

Usage

$3

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

const url = 'xxxx';

init(http, url);
`

$3

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

$3

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

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

API

$3

- [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

$3

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

$3

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

$3

- [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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

- [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 工具函数

$3

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

#### 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;
function ApiSortsDestructure(sorts: SC.API.Sorts[]): Record;
`

参数:

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

返回值:

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

示例:

`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
`

$3

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

#### 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;
function ApiQueryDestructure(queries: SC.API.Query[]): Record;
`

参数:

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

返回值:

返回 Record 类型的键值对对象，键为查询字段名，值为查询的值。

示例:

`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
`

$3

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' }]
``