little-wheels 1.2.14 → 1.3.1

package/README.md

@@ -1,45 +1,312 @@
-[keyClock登录](/docs/Login.md)
-
-#### v1.2.12
-- 修复登出时缺少 `id_token` 导致的问题
-
-#### v1.2.11
-- 修复独立鉴权模式下的 401 响应处理
-
-#### v1.2.10
-- 新增 `setTokenStr` 方法用于仅设置 Access Token
-- 更新 `.npmrc` 配置文件
-
-#### v1.2.9
-- 修复 SSO 用户组类型判断逻辑
-
-#### v1.2.8
-- 修复 SSO 登录分组数据匹配失败时返回 `null`
-- 添加 `.npmrc` 配置文件
-
-#### v1.2.7
-- 添加根据 `groupId` 获取分公司信息的方法
-
-#### v1.2.6
-- 支持传入初始 `token` 参数
-
-#### v1.2.5
-- 支持自定义基础 URL 配置
-
-#### v1.2.4
-- 将请求参数从 body 移动到 URL 查询字符串
-
-#### v1.2.3
-- 更新用户组列表接口地址
-
-#### v1.2.2
-- 支持 TypeScript 类型导出声明
-
-#### v1.2.1
-- Login 模块移除所有静态方法，调用方式发生变化
-
-#### v1.2.0
-- 新增 react-hooks
-
-#### v1.1.0
-- 新增 Login 模块
+# little-wheels
+
+一个面向 React + TypeScript 项目的轻量工具库，提供 SSO 登录、用户与组织查询接口，以及常用 React Hooks。
+
+## 功能
+
+| 模块 | 说明 |
+| --- | --- |
+| `AuthLogin` | SSO 登录、登出、Token 存取、刷新与解析 |
+| `useSSOApi` | 用户、角色、公司和分组查询接口 |
+| `LocalStorageUtil` | 按应用 ID 隔离的本地存储工具 |
+| `useAudio` | 音频播放状态与控制 |
+| `usePage` | 列表分页、查询和重置状态管理 |
+
+## 安装
+
+```bash
+pnpm add little-wheels
+```
+
+也可以使用 `npm install little-wheels` 或 `yarn add little-wheels`。
+
+## SSO 登录
+
+### 快速开始
+
+```typescript
+import { AuthLogin } from "little-wheels";
+
+const authLogin = new AuthLogin({
+  APPID: "your-app-id",
+});
+
+async function bootstrap() {
+  if (!authLogin.getTokenInfo()) {
+    // 首次访问会跳转至登录页；登录回调时会自动换取并保存 Token。
+    await authLogin.SSOLogin();
+  }
+
+  console.log(authLogin.getDecodeToken());
+}
+
+void bootstrap();
+
+// 退出登录
+// authLogin.logout();
+```
+
+`AuthLogin` 从 `v1.2.1` 起使用实例方法，请勿再通过 `AuthLogin.getTokenInfo()` 等静态方式调用。
+
+### 配置项
+
+```typescript
+interface AuthLoginType {
+  APPID: string;
+  dev?: boolean;
+  baseURL?: string;
+  token?: string;
+}
+```
+
+| 参数 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `APPID` | 是 | - | 应用唯一标识，同时用于隔离本地 Token |
+| `dev` | 否 | `false` | 开发环境标记，影响 IP 地址访问时的 Keycloak 地址处理 |
+| `baseURL` | 否 | `""` | API 请求基础地址；为空时使用当前域名 |
+| `token` | 否 | `""` | 初始 Access Token，适用于独立鉴权场景 |
+
+前后端分离开发时，需要将 `/lxwork/api` 和 `/sso` 代理到认证服务。例如：
+
+```typescript
+// vite.config.ts
+export default {
+  server: {
+    proxy: {
+      "/lxwork/api": {
+        target: "https://your-sso-host.example.com",
+        changeOrigin: true,
+      },
+      "/sso": {
+        target: "https://your-sso-host.example.com",
+        changeOrigin: true,
+      },
+    },
+  },
+};
+```
+
+### 常用方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `SSOLogin()` | 执行 SSO 登录或处理登录回调 |
+| `login()` | 直接跳转至登录页 |
+| `logout()` | 清除 Token 并跳转至登出页 |
+| `getTokenInfo()` | 获取完整 Token 信息 |
+| `getToken()` | 获取 Access Token |
+| `getRefreshToken()` | 获取 Refresh Token |
+| `getDecodeToken()` | 解析当前 Access Token |
+| `setToken(data, type?)` | 保存完整 Token 信息 |
+| `setTokenStr(token)` | 仅保存 Access Token 字符串 |
+| `refreshToken(forceRefresh?)` | Token 临近过期时刷新；传入 `true` 可强制刷新 |
+| `removeToken()` | 清除本地 Token |
+| `getCompanyList()` | 获取公司列表 |
+| `getUserBranchGroup()` | 获取当前用户所属分公司名称 |
+| `getUserBranchGroupByGroupId({ groupId })` | 根据分组 ID 获取所属分公司信息 |
+
+### 独立 Token 鉴权
+
+适用于 App WebView 等由外部传入 Access Token、无需发起完整 SSO 登录的场景：
+
+```typescript
+import { AuthLogin, useSSOApi } from "little-wheels";
+
+const authLogin = new AuthLogin({ APPID: "your-app-id" });
+const token = new URLSearchParams(window.location.search).get("token");
+
+if (token) {
+  authLogin.setTokenStr(token);
+}
+
+const userInfo = await useSSOApi(authLogin).getUserInfo();
+```
+
+## 请求 API
+
+`useSSOApi` 接收一个 `AuthLogin` 实例。请求会自动携带 Bearer Token，并在常规业务接口返回 `401` 时合并并发重登录，然后重试一次。
+
+```typescript
+import { AuthLogin, useSSOApi } from "little-wheels";
+
+const authLogin = new AuthLogin({ APPID: "your-app-id" });
+const api = useSSOApi(authLogin);
+
+const currentUser = await api.getUserDetail();
+const users = await api.getUsers({
+  real_name: "张三",
+  exact: false,
+  first: 0,
+  max_size: 20,
+});
+```
+
+所有路径都会自动拼接构造 `AuthLogin` 时传入的 `baseURL`。
+
+| 方法 | 请求 |
+| --- | --- |
+| `getTokenInfo(params)` | `GET /lxwork/api/auth/token?{查询参数}` |
+| `createPermissionTicket(data)` | `POST /lxwork/api/auth/create-permission-ticket` |
+| `getAuthTokenInfo(data)` | `POST /sso/realms/myrealm/protocol/openid-connect/token` |
+| `refreshAuthToken(refreshToken?)` | `GET /lxwork/api/auth/refresh` |
+| `getCompanyList()` | `GET /lxwork/api/auth/groups/branch` |
+| `getUserGroupList()` | `GET /lxwork/api/auth/users/groups` |
+| `getUserInfo()` | `GET /lxwork/api/auth/userinfo` |
+| `getUserDetail()` | `GET /lxwork/api/auth/users/detail` |
+| `getUserDetailById({ id })` | `GET /lxwork/api/auth/users/{id}` |
+| `getUsers(params)` | `GET /lxwork/api/auth/users/search?{查询参数}` |
+| `getUsersByRole(params)` | `GET /lxwork/api/auth/users/search-by-role?{查询参数}` |
+| `getCurUserGroupList()` | `GET /lxwork/api/auth/users/groups-parsed` |
+| `getAllRoles()` | `GET /lxwork/api/auth/users/all-roles` |
+| `getCurUserRoles()` | `GET /lxwork/api/auth/users/role-mappings` |
+| `getGroupByParentId(params)` | `GET /lxwork/api/auth/groups?{查询参数}` |
+| `getAllGroup()` | `GET /lxwork/api/auth/groups/all` |
+| `getGroupsByName(params)` | `GET /lxwork/api/auth/groups/search?{查询参数}` |
+| `getGroupDetail({ id })` | `GET /lxwork/api/auth/groups/{id}` |
+| `getChildrenGroup({ group_id })` | `GET /lxwork/api/auth/groups/{group_id}/children-parse` |
+| `getUsersByGroup(params)` | `GET /lxwork/api/auth/groups/{group_id}/members?{查询参数}` |
+
+参数和返回值均已提供 TypeScript 类型声明，可直接通过编辑器查看。
+
+## React Hooks
+
+Hooks 会单独构建到 `dist/react-hooks/index.es.js`。
+
+### useAudio
+
+```typescript
+import { useAudio } from "little-wheels/dist/react-hooks/index.es.js";
+
+const {
+  currentTime,
+  duration,
+  isPlaying,
+  volume,
+  playRate,
+  audioPlay,
+  audioPause,
+  togglePlay,
+  setAudioCurrentTime,
+  setAudioVolume,
+  setAudioRate,
+} = useAudio({
+  src: "/audio/example.mp3",
+  onError: (error) => console.error(error),
+});
+```
+
+- 音量范围为 `0` 到 `1`。
+- 播放倍速范围为 `0.5` 到 `4`。
+- `audioPlay(url?)` 和 `togglePlay(url?)` 可在调用时切换音频地址。
+
+### usePage
+
+```typescript
+import { usePage } from "little-wheels/dist/react-hooks/index.es.js";
+
+const {
+  state,
+  listLoading,
+  getTableData,
+  onPageInfoChange,
+  reset,
+} = usePage<User>({
+  defaultPageInfo: { pageNum: 1, pageSize: 20 },
+  getListApi: (params) => fetchUserList(params),
+  customQueryParameters: () => ({ enabled: true }),
+});
+
+console.log(state.tableData, state.total, state.pageInfo);
+```
+
+`getListApi` 可以返回数组，也可以返回包含 `dataList`、`list` 和 `total` 字段的对象。传入的 `form` 如包含 `getFieldsValue()` 和 `resetFields()`，会自动参与查询与重置。
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm start
+pnpm build
+```
+
+- `pnpm start`：启动示例项目，默认端口为 `3000`。
+- `pnpm build`：生成 ESM 构建产物和 TypeScript 声明文件。
+
+## 版本记录
+
+### v1.3.1
+
+- 修正获取所有分组的接口地址为 `/lxwork/api/auth/groups/all`
+- 补充 Login 请求方法的 URL 注释与项目使用文档
+
+### v1.3.0
+
+- 优化 SSO 回调参数校验和 URL 参数清理逻辑
+- 登录及登出重定向地址会移除 SSO 回调参数
+
+### v1.2.14
+
+- 合并同一实例的并发重登录，避免多个 `401` 重复跳转
+- 优化多实例场景下的 Token 清理逻辑
+
+### v1.2.13
+
+- `refreshAuthToken` 支持传入自定义 Refresh Token
+
+### v1.2.12
+
+- 修复登出时缺少 `id_token` 导致的问题
+
+### v1.2.11
+
+- 修复独立鉴权模式下的 `401` 响应处理
+
+### v1.2.10
+
+- 新增 `setTokenStr` 方法用于仅设置 Access Token
+- 更新 `.npmrc` 配置文件
+
+### v1.2.9
+
+- 修复 SSO 用户组类型判断逻辑
+
+### v1.2.8
+
+- 修复 SSO 登录分组数据匹配失败时返回 `null`
+- 添加 `.npmrc` 配置文件
+
+### v1.2.7
+
+- 添加根据 `groupId` 获取分公司信息的方法
+
+### v1.2.6
+
+- 支持传入初始 `token` 参数
+
+### v1.2.5
+
+- 支持自定义基础 URL 配置
+
+### v1.2.4
+
+- 将请求参数从 body 移动到 URL 查询字符串
+
+### v1.2.3
+
+- 更新用户组列表接口地址
+
+### v1.2.2
+
+- 支持 TypeScript 类型导出声明
+
+### v1.2.1
+
+- Login 模块移除所有静态方法，调用方式发生变化
+
+### v1.2.0
+
+- 新增 React Hooks
+
+### v1.1.0
+
+- 新增 Login 模块

package/dist/index.d.ts

@@ -281,6 +281,8 @@ export declare interface PermissionItem {
 
 export declare function removeUrlParam(paramsArr: string[]): void;
 
+export declare function removeUrlParams(url: string, paramsArr: string[]): string;
+
 export declare interface RoleItem {
     id: number;
     position_type_id: number;
@@ -378,26 +380,56 @@ export declare interface UserRoleItem {
 }
 
 export declare const useSSOApi: (authLogin: AuthLogin) => {
+    /**
+     * 获取令牌信息
+     * 请求 URL：GET /lxwork/api/auth/token?{查询参数}
+     */
     getTokenInfo: (params: SearchTokenParams) => Promise<TokenInfoType<number>>;
+    /**
+     * 创建权限票据
+     * 请求 URL：POST /lxwork/api/auth/create-permission-ticket
+     */
     createPermissionTicket: (data: {
         client_id: string;
     }) => Promise<{
         ticket: string;
     }>;
+    /**
+     * 使用权限票据获取认证令牌
+     * 请求 URL：POST /sso/realms/myrealm/protocol/openid-connect/token
+     */
     getAuthTokenInfo: (data: {
         grant_type: string;
         ticket: string;
     }) => Promise<TokenInfoType<number>>;
+    /**
+     * 刷新认证令牌
+     * 请求 URL：GET /lxwork/api/auth/refresh
+     */
     refreshAuthToken: (refreshToken?: string) => Promise<TokenInfoType<number>>;
+    /**
+     * 获取所有分公司
+     * 请求 URL：GET /lxwork/api/auth/groups/branch
+     */
     getCompanyList: () => Promise<CompanyItem[]>;
+    /**
+     * 获取当前用户所属分组
+     * 请求 URL：GET /lxwork/api/auth/users/groups
+     */
     getUserGroupList: () => Promise<UserGroupItem[]>;
+    /**
+     * 获取当前登录用户信息
+     * 请求 URL：GET /lxwork/api/auth/userinfo
+     */
     getUserInfo: () => Promise<UserInfo>;
     /**
      * 获取当前登录用户详细信息
+     * 请求 URL：GET /lxwork/api/auth/users/detail
      */
     getUserDetail: () => Promise<UserDetail>;
     /**
      * 获取当前登录用户详细信息
+     * 请求 URL：GET /lxwork/api/auth/users/{id}
      * @param id 用户id
      */
     getUserDetailById: ({ id }: {
@@ -405,6 +437,7 @@ export declare const useSSOApi: (authLogin: AuthLogin) => {
     }) => Promise<OriginUserDetail>;
     /**
      * 根据工号姓名等搜索用户
+     * 请求 URL：GET /lxwork/api/auth/users/search?{查询参数}
      * @param params.username 工号  至少四个字符
      * @param params.real_name 姓名  至少两个字符
      * @param params.exact 是否精确查找, 如果为 true 只返回完全匹配的记录, 否则返回模糊匹配的记录
@@ -424,6 +457,7 @@ export declare const useSSOApi: (authLogin: AuthLogin) => {
     }) => Promise<SearchUserItem[]>;
     /**
      * 根据角色名称搜索用户列表（带分页）
+     * 请求 URL：GET /lxwork/api/auth/users/search-by-role?{查询参数}
      * @param params 查询参数对象
      * @param params.role_name 必填，角色名称（需完全匹配）
      * @param params.name 可选，用户姓名模糊搜索（支持部分匹配）
@@ -440,21 +474,25 @@ export declare const useSSOApi: (authLogin: AuthLogin) => {
     /**
      * 获取当前用户可用的分公司或业务组
      * 如果当前用户属于分公司，则返回分公司及下属分公司，如果属于分公司下的部门，则返回部门下的业务组， 如果属于业务组，则返回业务组
+     * 请求 URL：GET /lxwork/api/auth/users/groups-parsed
      * @returns Promise<CompanyItem[]>
      */
     getCurUserGroupList: () => Promise<CompanyItem[]>;
     /**
      * 获取所有岗位角色名称
+     * 请求 URL：GET /lxwork/api/auth/users/all-roles
      * @returns Promise<RoleItem[]>
      */
     getAllRoles: () => Promise<RoleItem[]>;
     /**
      * 获取当前用户Roles
+     * 请求 URL：GET /lxwork/api/auth/users/role-mappings
      * @returns Promise<UserRoleItem[]>
      */
     getCurUserRoles: () => Promise<UserRoleItem[]>;
     /**
      * 获取所属 parent_id 下分组
+     * 请求 URL：GET /lxwork/api/auth/groups?{查询参数}
      * @param params.parent_id 可选，分组的父级id
      * 接口文档 不统一  GroupItem UserGroupItem 字段有下划线 有驼峰
      * @returns Promise<GroupItem[]>
@@ -464,11 +502,13 @@ export declare const useSSOApi: (authLogin: AuthLogin) => {
     }) => Promise<GroupItem[]>;
     /**
      * 获取所有分组
+     * 请求 URL：GET /lxwork/api/auth/groups/all
      * @returns Promise<GroupItem[]>
      */
     getAllGroup: () => Promise<GroupItem[]>;
     /**
      * 按组名搜索组, 按树结构返回匹配的组，以及这个组的上级组, 直到根节点
+     * 请求 URL：GET /lxwork/api/auth/groups/search?{查询参数}
      * @param params.search 搜索组， 不少于2个字符
      * @param params.max 返回结果数， keycloak 默认返回 11 个， 如何希望返回所有，可以设一个较大值
      * @returns Promise<GroupItem[]> 会按照树形结构返回所有符合搜索条件的树形结果
@@ -479,6 +519,7 @@ export declare const useSSOApi: (authLogin: AuthLogin) => {
     }) => Promise<GroupItem[]>;
     /**
      * 获取组的详细信息
+     * 请求 URL：GET /lxwork/api/auth/groups/{id}
      * @returns Promise<UserGroupItem>
      */
     getGroupDetail: ({ id }: {
@@ -486,6 +527,7 @@ export declare const useSSOApi: (authLogin: AuthLogin) => {
     }) => Promise<UserGroupItem>;
     /**
      * 获取某个分公司或分公司部门下的所有下级业务组
+     * 请求 URL：GET /lxwork/api/auth/groups/{group_id}/children-parse
      * @param group_id 分组id
      * @returns Promise<CompanyItem[]>
      */
@@ -494,6 +536,7 @@ export declare const useSSOApi: (authLogin: AuthLogin) => {
     }) => Promise<CompanyItem[]>;
     /**
      * 获取某个分组下的所有用户
+     * 请求 URL：GET /lxwork/api/auth/groups/{group_id}/members?{查询参数}
      * @param group_id  分组id
      * @param params.first Pagination offset, 从 0 开始
      * @param params.max_size Maximum results size (defaults to 100)