hrp-ui-base 1.4.4 → 1.4.5

package/README.md

@@ -1,163 +1,51 @@
 # hrp-ui-base
 
-`hrp-ui-base` 是从 `ui-hrp-main` monorepo 中拆出的前端公共基础包，包含公共 Vue 组件、通用工具方法和基础样式。
-
-## 安装
-
-```bash
-npm i hrp-ui-base
-```
-
-如果业务项目尚未安装以下 peer 依赖，需要一并安装：
-
-```bash
-npm i vue element-plus vant
-```
-
-## 全局注册组件
-
-```ts
-import { createApp } from "vue";
-import ElementPlus from "element-plus";
-import HrpUiBase from "hrp-ui-base";
-import "element-plus/dist/index.css";
-import "hrp-ui-base/styles/main.css";
-import App from "./App.vue";
-
-const app = createApp(App);
-
-app.use(ElementPlus);
-app.use(HrpUiBase);
-app.mount("#app");
-```
-
-注册后可直接使用：
-
-```vue
-<template>
-  <AnnexUpload page-id="demo-page" />
-  <ListSearchContent />
-</template>
-```
-
-## 按需引用组件
-
-```vue
-<script setup lang="ts">
-import { AnnexUpload, AnnexImgUpload, ListSearchContent } from "hrp-ui-base";
-import "hrp-ui-base/styles/main.css";
-</script>
-```
-
-也可以从组件入口引用：
-
-```ts
-import { AnnexUpload } from "hrp-ui-base/components";
-```
-
-## 引用工具方法
-
-```ts
-import { HttpUtil, Throttle, getFileType, ddWindowOpen } from "hrp-ui-base";
-```
-
-也可以引用独立工具文件：
-
-```ts
-import HttpUtil from "hrp-ui-base/utils/HttpUtil";
-import { IsPc, IsPhone } from "hrp-ui-base/utils/get-env";
-```
-
-## 业务 API 引用规则
-
-业务 API 不从 `hrp-ui-base` 引用。各业务项目需要在自身 `src/api` 下维护 Controller、VO/BO 类型，并通过 `@/api/...` 引用：
-
-```ts
-import HomeController from "@/api/bms/home/HomeController";
-import type HomeMenu from "@/api/bms/home/bo/HomeMenu";
-```
-
-`ui-base/src/api` 仅保留公共组件自身运行需要的少量内部 API，例如附件上传、列表配置、权限和字典配置，不作为业务项目的 API 入口。
-
-## 路由相关工具注入
-
-`exitLogin` 和 `router-utils` 已从业务项目的 `@/router`、store 中解耦。业务项目需要使用这些能力时，在入口处注入运行时上下文：
-
-```ts
-import router from "@/router";
-import store from "@/stores/routeStore";
-import { funcRoleStore } from "@/stores/funcRole";
-import { setExitLoginRouter, setRouterUtilsContext } from "hrp-ui-base";
-
-setExitLoginRouter(router);
-setRouterUtilsContext({
-  router,
-  routeStoreList: funcRoleStore(store),
-});
-```
-
-## 从旧 workspace 包迁移
-
-旧写法：
-
-```ts
-import { ListSearchContent } from "custom-components";
-import { HttpUtil } from "custom-utils";
-```
-
-新写法：
-
-```ts
-import { ListSearchContent, HttpUtil } from "hrp-ui-base";
-import HomeController from "@/api/bms/home/HomeController";
-```
-
-如果业务项目暂时不能一次性替换所有旧导入，可以先在 Vite 和 TypeScript 中做兼容别名：
-
-```ts
-// vite.config.ts
-resolve: {
-  alias: {
-    "custom-components": "hrp-ui-base",
-    "custom-utils": "hrp-ui-base",
-  },
-}
-```
-
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "paths": {
-      "custom-components": ["node_modules/hrp-ui-base/src/index.ts"],
-      "custom-utils": ["node_modules/hrp-ui-base/src/index.ts"],
-      "custom-utils/*": ["node_modules/hrp-ui-base/src/*"]
-    }
-  }
-}
-```
-
-## 本地开发与发布
-
-```bash
-cd ui-base
-npm install
-npm run build
-npm publish
-```
-
-发布后业务项目即可通过 `npm i hrp-ui-base` 安装。
-
-## 目录说明
-
-```text
-ui-base/
-├── src/components   # 公共 Vue 组件
-├── src/styles       # 公共样式
-├── src/utils        # 通用工具方法
-├── src/api          # 公共组件内部使用的少量 API
-├── src/assets       # 公共静态资源
-├── src/index.ts     # 统一入口
-├── src/components.ts
-└── src/utils.ts
-```
+## 项目定位
+`hrp-ui-base` 是各拆分业务系统共同依赖的前端公共能力包，用来承接主仓原 `custom-components`、`custom-utils` 中可复用的组件、布局、请求、权限、样式和工具能力。该包本身不是业务应用，不直接对应某一个后端服务。
+
+## 对接后端服务
+- 无独立业务后端。
+- 包内保留少量公共接口封装和类型，供业务系统复用：`bms`、`hrms`、`notice`、`work-order-pc`、`common`。
+- 请求能力由 `HttpUtil`、业务系统运行时 token、代理和后端网关共同决定。
+
+## 提供的公共组件
+- `CustomButton`：统一按钮封装。
+- `CustonSwitch`：统一开关封装。
+- `AnnexUpload`：通用附件上传。
+- `AnnexImgUpload`：图片附件上传。
+- `AnnexUploadWeijian`：卫健场景附件上传。
+- `ListSearchContent`：列表页筛选/查询区域容器。
+- `BaseLayout`：基础页面布局。
+- `LayoutContainer`：业务系统主布局，整合菜单、页签、头部、消息、审批、导出中心、主题和字号配置。
+- `SysHeader`、`SysHeaderLeft`、`SysHeaderRight`、`SysHeaderTabs`：系统头部与页签组件。
+- `SideMenu`、`SideMenuSonList`：侧边菜单与子菜单列表。
+- `MessageNotificationDrawer`：消息通知抽屉。
+- `ApprovalCenterDrawer`：审批中心抽屉。
+- `ExportCenterDrawer`：导出中心抽屉。
+- `PersonalizationGuideDialog`：个性化引导弹窗。
+- 布局子组件：暗黑模式、字号、菜单位置、下载、待办、消息、头像等 Header 功能块。
+
+## 提供的公共工具能力
+- 请求与登录：`HttpUtil`、`exitLogin`、`setExitLoginRouter`。
+- 权限与路由：`isHavePermit`、`getPagePermit`、`toNoPermitPage`、路由/路径工具。
+- 表格与主题：`tableHeaderCellStyle`、`tableFontCellStyle`、日夜模式样式配置。
+- 文件与下载：`download`、文件类型判断、钉钉打开/下载相关工具。
+- 交互工具：`Throttle`、`Debounce`、`debounceleading`、WebSocket 封装。
+- 数据工具：字典、字符串、校验、格式化、过滤、树/列表转换等。
+- 公共类型：`ResponseBean`、`ResponseBeanList`、`ResponseBeanTablePage`、`TableQueryCriteriaVO`、`FileBaseInfo`。
+
+## 使用方式
+- 全局安装：`app.use(HrpUiBase)`。
+- 按需引用：`import { LayoutContainer, ListSearchContent, HttpUtil } from "hrp-ui-base"`。
+- 包入口：`src/index.ts` 同时导出组件、API 类型/控制器和工具函数。
+
+## 技术说明
+- 包名：`hrp-ui-base`，当前版本：`1.4.4`。
+- 技术栈：Vue 3、TypeScript、Vite library mode。
+- 构建：`pnpm build`；类型检查：`pnpm typecheck`。
+- 组件样式入口在 `src/styles/main.css`，业务系统更新版本后需要重新安装依赖并构建验证。
+
+## 维护注意
+- 新增公共组件时，需要在 `src/components.ts` 中注册、导出并补充 Vue 全局组件声明。
+- 新增工具时，需要在 `src/utils.ts` 统一导出。
+- 影响登录、401、消息通知、审批中心、菜单跳转等能力时，需要在 entry 和主要拆分系统中回归验证。