@alanwang-merit/meritdata-platform-skill-package 1.0.9 → 1.0.11

package/skills/meritdata-platform-frontend/references/components.md

@@ -1,284 +1,425 @@
-# 平台前端组件清单（components）
-
-> 平台提供的 Vue/React 组件，按需引入，不全量打包。
-
----
-
-## 1. 选择类组件
-
-### 1.1 人员选择（UserSelector）
-
-```vue
-<template>
-  <UserSelector
-    v-model="selectedUserIds"
-    :multiple="true"
-    :show-org="true"
-    @change="handleChange"
-  />
-</template>
-
-<script setup>
-import { UserSelector } from '@meritdata/platform-ui';
-
-const selectedUserIds = ref([]);
-function handleChange(users) {
-  console.log('已选用户：', users);
-  // users: [{ id, name, orgName, ... }]
+## 概述
+
+所有组件来自 `cloud-module-base` npm 包，已通过 `Vue.use(base)` 全局安装。组件支持国际化（`$t()`）、密级标签、EventBus 通信。
+
+---
+
+## 组件速查表
+
+| 组件 | 用途 | 典型场景 |
+|------|------|----------|
+| CloudDialog | 通用对话框（密级标签/异步关闭） | 所有弹窗场景 |
+| UserSelect | 人员选择（单选/多选、按组织/角色） | 指定处理人、审批人 |
+| UserSelectMulti | 增强版人员选择（多维度） | 批量选人、三员申请 |
+| DeptSelect | 部门树选择 | 选择所属部门 |
+| RoleSelect | 角色树选择 | 选择授权角色 |
+| ImportButton | 数据导入（模板下载/验证/上传） | Excel 批量导入 |
+| MenuAuth | 菜单权限控制（包裹即隐藏） | 页面访问控制 |
+| ResourceCodeAuth | 按钮级资源权限 | 按钮显示控制 |
+| ThreeMemberAuth | 三员角色权限（安全/审计/管理） | 安全敏感操作 |
+| TableHeadSearch | 表格列筛选 | 列表页表头筛选 |
+| VerifiyPassword | 二级密码验证弹窗 | 敏感操作二次确认 |
+| CommonHeader | 通用页面头部（面包屑+密级） | 页面布局 header |
+
+---
+
+## 1. CloudDialog — 通用对话框
+
+**导入**: `import cloudDialog from 'cloud-module-base/packages/cloud-dialog'`
+
+### Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| visible | Boolean | null | 控制显示/隐藏，支持 `.sync` |
+| title | String | '' | 标题 |
+| tip | String/null | null | 密级标签 |
+| beforeClose | Function | null | 关闭前钩子（异步） |
+| showSecretLabel | Boolean | true | 是否显示密级标签 |
+
+### 使用示例
+
+```vue
+<cloud-dialog
+  :title="'编辑信息'"
+  :visible.sync="dialogVisible"
+  width="600px"
+  top="8vh"
+  :before-close="handleClose"
+  :close-on-click-modal="false"
+  append-to-body
+>
+  <div>内容区域</div>
+  <template #footer>
+    <el-button @click="dialogVisible = false">取消</el-button>
+    <el-button type="primary" @click="handleConfirm">确定</el-button>
+  </template>
+</cloud-dialog>
+```
+
+---
+
+## 2. UserSelect — 人员选择
+
+**导入**: `import userSelect from 'cloud-module-base/packages/user-select'`
+
+### options 配置项
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | String | — | 对话框标题 |
+| selectType | String | 'org' | 选人模式：org/role/workgroup/category |
+| orgUrl | String | — | 组织树接口 |
+| selectedUsers | Array | [] | 已选人员 ID 集合 |
+| filterSwitch | Boolean | false | 是否过滤已选 |
+| isShowNoUser | Boolean | true | 是否过滤无账户人员 |
+
+### Events
+
+| 事件 | 说明 |
+|------|------|
+| dialog-save | 确认选择，返回选中人员数组 |
+| dialog-close | 关闭对话框 |
+
+### 使用示例
+
+```vue
+<user-select
+  :showSecretLabel="true"
+  :dialogVisible="dialogVisibleUser"
+  :options="optionsUser"
+  @dialog-close="dialogClose"
+  @dialog-save="dialogSaveUser"
+/>
+```
+
+```javascript
+data() {
+  return {
+    dialogVisibleUser: false,
+    optionsUser: { selectedUsers: [] }
+  }
+},
+methods: {
+  dialogSaveUser(selectedUser) {
+    const codes = selectedUser.map(u => u.code).join(',');
+    const names = selectedUser.map(u => u.name).join(',');
+    this.formData.userConfigIds = codes;
+    this.formData.userConfigNames = names;
+    this.dialogVisibleUser = false;
+  }
+}
+```
+
+---
+
+## 3. UserSelectMulti — 增强版人员选择
+
+**导入**: `import userSelectMulti from 'cloud-module-base/packages/user-select-multi'`
+
+### options 配置项
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | String | — | 对话框标题 |
+| selectType | String | 'all' | 选人模式：org/role/workgroup/category/duty/all |
+| selectedUsers | Array | [] | 已选人员 |
+| limit | Number | null | 人数上限 |
+| radioFlag | Boolean | false | 单选模式 |
+| threeMemberApply | Boolean | false | 三员申请模式 |
+
+### 使用示例
+
+```vue
+<user-select-multi
+  :showSecretLabel="true"
+  :dialogVisible="editDialogVisible"
+  :options="options"
+  @dialog-close="editDialogClose"
+  @dialog-save="editDialogSave"
+/>
+```
+
+---
+
+## 4. DeptSelect — 部门选择
+
+**导入**: `import deptSelect from 'cloud-module-base/packages/dept-select'`
+
+### options 配置项
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | String | — | 对话框标题 |
+| treeUrl | String | '/api/ou/org/orgDeptTree' | 部门树接口 |
+| checkedIds | Array | [] | 默认选中 ID 列表 |
+
+### 使用示例
+
+```vue
+<dept-select
+  :showSecretLabel="true"
+  :dialogVisible="dialogVisibleDept"
+  :options="optionsDept"
+  @dialog-close="dialogClose"
+  @dialog-save="dialogSaveDept"
+/>
+```
+
+```javascript
+dialogSaveDept(selectedDept) {
+  const codes = selectedDept.map(d => d.code).join(',');
+  const names = selectedDept.map(d => d.name).join(',');
+  this.formData.deptConfigIds = codes;
+  this.formData.deptConfigNames = names;
+  this.dialogVisibleDept = false;
+}
+```
+
+---
+
+## 5. RoleSelect — 角色选择
+
+**导入**: `import roleSelect from 'cloud-module-base/packages/role-select'`
+
+### options 配置项
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| title | String | — | 对话框标题 |
+| treeUrl | String | '/api/ou/org/orgRoleTree' | 角色树接口 |
+| checkedIds | Array | [] | 默认选中 ID 列表 |
+
+### 使用示例
+
+```vue
+<role-select
+  :dialogVisible="dialogVisibleRole"
+  :options="optionsRoles"
+  @dialog-close="dialogClose"
+  @dialog-save="dialogSaveRole"
+/>
+```
+
+---
+
+## 6. ImportButton — 导入按钮
+
+**导入**: `import importButton from 'cloud-module-base/packages/import-button'`
+
+### options 配置项
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| applicationName | String | 应用名称 |
+| configId | String | 导入配置 ID |
+| text | String | 按钮文本，默认'导入' |
+| rootOrgCode | String | 根组织编码 |
+| rootOrgId | String | 根组织 ID |
+| rootDLevelCode | String | 密级编码 |
+
+### Events
+
+| 事件 | 说明 |
+|------|------|
+| requestGridData | 导入完成或取消后刷新列表 |
+
+### 使用示例
+
+```vue
+<cloud-import-button
+  buttonCode="{buttonCode}"
+  :disabled_custom="canShowImport"
+  :options="importOpts"
+  class="marL8"
+  @requestGridData="requestGridData"
+/>
+```
+
+```javascript
+importOpts: {
+  applicationName: '{applicationName}',
+  configId: '{importConfigId}',
+  rootOrgCode: '{rootOrgCode}',
+  rootOrgId: '{rootOrgId}',
+  rootDLevelCode: '{rootDLevelCode}'
 }
-</script>
-```
-
-**Props**：
-
-| prop | 类型 | 默认 | 说明 |
-|------|------|------|------|
-| `v-model` | `string[]` | - | 选中用户 ID 列表 |
-| `multiple` | `boolean` | `false` | 是否多选 |
-| `showOrg` | `boolean` | `true` | 是否显示组织信息 |
-| `disabled` | `boolean` | `false` | 是否禁用 |
-| `placeholder` | `string` | `"请选择人员"` | 占位文本 |
-
----
-
-### 1.2 组织树选择（OrgTreeSelector）
-
-```vue
-<template>
-  <OrgTreeSelector
-    v-model="selectedOrgId"
-    :multiple="false"
-    :show-root="true"
-  />
-</template>
-
-<script setup>
-import { OrgTreeSelector } from '@meritdata/platform-ui';
-const selectedOrgId = ref('');
-</script>
-```
-
----
-
-### 1.3 部门选择（DeptSelector）
-
-```vue
-<template>
-  <DeptSelector
-    v-model="selectedDeptIds"
-    :org-id="currentOrgId"
-    :multiple="true"
-  />
-</template>
-```
-
----
-
-### 1.4 角色选择（RoleSelector）
-
-```vue
-<template>
-  <RoleSelector
-    v-model="selectedRoleCodes"
-    :org-id="currentOrgId"
-  />
-</template>
-```
-
----
-
-### 1.5 字典下拉（LookupSelect）
-
-```vue
-<template>
-  <LookupSelect
-    v-model="status"
-    lookup-type="ORDER_STATUS"
-    placeholder="请选择状态"
-  />
-</template>
-
-<script setup>
-import { LookupSelect } from '@meritdata/platform-ui';
-const status = ref('');
-</script>
-```
-
-**Props**：
-
-| prop | 类型 | 说明 |
-|------|------|------|
-| `lookup-type` | `string` | 字典类型 code |
-| `v-model` | `string` | 选中 code（不是 name）|
-
----
-
-## 2. 表单类组件
-
-### 2.1 资源选择（ResourceSelector）
-
-```vue
-<template>
-  <ResourceSelector
-    v-model="selectedResourceIds"
-    resource-type="MENU"
-    :multiple="true"
-  />
-</template>
-```
-
-### 2.2 文件上传（FileUpload）
-
-```vue
-<template>
-  <FileUpload
-    v-model="fileIds"
-    biz-type="PURCHASE_ORDER_CONTRACT"
-    :biz-id="orderId"
-    :max-size="50"
-    :accept="['.pdf', '.docx']"
-  />
-</template>
-```
-
-### 2.3 富文本编辑器（RichEditor）
-
-```vue
-<template>
-  <RichEditor
-    v-model="content"
-    :height="300"
-    :toolbar="['bold', 'italic', 'link', 'image']"
-  />
-</template>
-```
-
----
-
-## 3. 展示类组件
-
-### 3.1 审批流图（ProcessViewer）
-
-```vue
-<template>
-  <ProcessViewer
-    :process-instance-id="processInstanceId"
-    :highlight-task-id="currentTaskId"
-  />
-</template>
-```
-
-### 3.2 操作日志（OperationLogList）
-
-```vue
-<template>
-  <OperationLogList
-    :biz-id="orderId"
-    :biz-type="'PURCHASE_ORDER'"
-  />
-</template>
-```
-
-### 3.3 用户头像（UserAvatar）
-
-```vue
-<template>
-  <UserAvatar :user-id="userId" :size="32" />
-</template>
-```
-
----
-
-## 4. 业务组件
-
-### 4.1 通用列表页（ListPage）
-
-```vue
-<template>
-  <ListPage
-    :query="query"
-    :fetch="fetchList"
-    :columns="columns"
-  >
-    <template #toolbar>
-      <el-button @click="handleCreate">新建</el-button>
-    </template>
-  </ListPage>
-</template>
-
-<script setup>
-import { ListPage } from '@meritdata/platform-ui';
-
-const query = ref({ keyword: '', status: '' });
-const columns = [
-  { prop: 'orderNo', label: '订单号', width: 180 },
-  { prop: 'applicantName', label: '申请人', width: 120 },
-  { prop: 'statusName', label: '状态', width: 100 },
-  { prop: 'createTime', label: '创建时间', width: 180 }
-];
-</script>
-```
-
-### 4.2 通用详情页（DetailPage）
-
-```vue
-<template>
-  <DetailPage :data="detail" :fields="fields" />
-</template>
-
-<script setup>
-import { DetailPage } from '@meritdata/platform-ui';
-
-const fields = [
-  { prop: 'orderNo', label: '订单号' },
-  { prop: 'applicantName', label: '申请人' },
-  { prop: 'statusName', label: '状态' }
-];
-</script>
-```
-
----
-
-## 5. ❌ 反模式
-
-### 5.1 ❌ 全量引入组件库
-
-```javascript
-// ❌ 错：打包体积大
-import * as PlatformUI from '@meritdata/platform-ui';
-app.use(PlatformUI);
-
-// ✅ 正确：按需引入
-import { UserSelector, LookupSelect } from '@meritdata/platform-ui';
-```
-
-### 5.2 ❌ 自己实现选择弹框
-
-```vue
-<!-- ❌ 错：自己写弹框 + 树形 + 搜索 -->
-<el-dialog v-model="visible">
-  <el-tree :data="orgTree" />
-  <el-input v-model="keyword" />
-  ...
-</el-dialog>
-```
-
-✅ 用 `UserSelector` / `OrgTreeSelector`，平台组件已经处理了搜索/分页/权限。
-
-### 5.3 ❌ 字典 value 用 name
-
-```vue
-<!-- ❌ 错：value 存中文 -->
-<LookupSelect v-model="statusName" />  <!-- "审批中" -->
-
-<!-- ✅ 正确：value 存 code -->
-<LookupSelect v-model="status" lookup-type="ORDER_STATUS" />  <!-- "PENDING" -->
-```
-
----
-
-## 6. 关联阅读
-
-- [project-structure.md](project-structure.md) — 工程结构
-- [auth-and-api.md](auth-and-api.md) — 权限与 API 调用
-- [SKILL.md](../SKILL.md)
+```
+
+---
+
+## 7. MenuAuth — 菜单权限
+
+**导入**: `import MenuAuth from 'cloud-module-base/packages/authenticate/menu-auth'`
+
+无需 props，包裹内容即可控制显示。当用户有页面菜单权限时显示内容。
+
+```vue
+<menu-auth>
+  <div>需要权限才能显示的内容</div>
+</menu-auth>
+```
+
+---
+
+## 8. ResourceCodeAuth — 按钮级资源权限
+
+**导入**: `import resourceCodeAuth from 'cloud-module-base/packages/resource-code-auth'`
+
+### Props
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| resourceCode | String | 是 | 资源代码 |
+| url | String | 是 | 授权验证 URL |
+
+```vue
+<resource-code-auth resourceCode="emp_export" url="/api/authority/resource/resource-code-auth">
+  <el-button>导出</el-button>
+</resource-code-auth>
+```
+
+---
+
+## 9. ThreeMemberAuth — 三员授权
+
+**导入**: `import threeMemberAuth from 'cloud-module-base/packages/three-member-auth'`
+
+### Props
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| roleCode | String | 是 | 角色代码，多个逗号分隔 |
+
+```vue
+<three-member-auth role-code="XTGLY,AQGLY">
+  <el-button type="primary" @click="addBtnClick">新增</el-button>
+  <el-button @click="deleteBtnClick">删除</el-button>
+</three-member-auth>
+```
+
+---
+
+## 10. TableHeadSearch — 表格列筛选
+
+**导入**: `import tableHeadSearch from 'cloud-module-base/packages/components/tableHeadSearch'`
+
+### Props
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| filedSearchName | String | 表头名称 |
+| showSelectFlag | Boolean | 是否显示选中标识 |
+| value / v-model | Boolean | popover 显示状态 |
+| checkList.sync | Array | 选中列表 |
+| filterList | Array | 筛选数据列表 |
+
+### Events
+
+| 事件 | 说明 |
+|------|------|
+| findTypeList | 确认筛选 |
+| resetTypeList | 重置筛选 |
+
+### 使用示例
+
+```vue
+<template slot="header" slot-scope="scope">
+  <table-head-search
+    ref="resetDLevelSearch"
+    filedSearchName="组织类型"
+    :showSelectFlag="dLevelSelectFlag"
+    v-model="showDLevelPopover"
+    :checkList.sync="dLevelLists"
+    :filterList="filterDLevelList"
+    @findTypeList="findDLevel"
+    @resetTypeList="resetDLevel"
+    @showList="resetDLevelModule"
+  />
+</template>
+```
+
+---
+
+## 11. VerifiyPassword — 二级密码验证
+
+**导入**: `import verifiyPassword from 'cloud-module-base/packages/components/verifiy-password'`
+
+### Props
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| dialogFormVisible | Boolean | 对话框显示状态 |
+| title | String | 标题 |
+
+### Events
+
+| 事件 | 说明 |
+|------|------|
+| close | 关闭弹窗 |
+| define | 验证通过确认 |
+
+### 使用示例
+
+```vue
+<verifiy-password
+  :title="'安全验证'"
+  :dialogFormVisible="jianquanVisible"
+  @close="dialogClose"
+  @define="handelConfirm"
+/>
+```
+
+```javascript
+methods: {
+  triggerVerify(code) {
+    this.buttonCode = code;
+    this.jianquanVisible = true;
+  },
+  handelConfirm() {
+    this.jianquanVisible = false;
+    if (this.buttonCode === 'user_delete') this.handleDeletes();
+  }
+}
+```
+
+---
+
+## 12. CommonHeader — 通用头部
+
+**导入**: `import commonHeader from 'cloud-module-base/packages/components/common-header'`
+
+包含面包屑导航和密级标签，用于页面顶部布局。
+
+```vue
+<template>
+  <el-header height="50px">
+    <el-row>
+      <el-col :span="12">
+        <v-header />
+      </el-col>
+      <el-col :span="12" style="text-align:right;line-height:50px;">
+        <el-button type="primary" @click="submitForm">保存</el-button>
+      </el-col>
+    </el-row>
+  </el-header>
+</template>
+
+<script>
+import header from 'cloud-module-base/packages/components/common-header';
+export default {
+  components: { 'v-header': header }
+}
+</script>
+```
+
+---
+
+## 组件注意事项
+
+1. 所有组件依赖 Element-UI，确保已全局安装
+2. CloudDialog 需引入样式: `import 'cloud-module-base/static/css/cloud-dialog.css'`
+3. 组件使用 `$t()` 国际化，需提前配置 i18n
+4. 组件间通过 `Vue.prototype.EventBus` 通信，不要覆盖 EventBus
+
+---