@agile-team/wl-skills-kit 2.3.0 → 2.3.1

package/files/docs/jh-user-picker.md

@@ -1,197 +1,197 @@
-# jh-user-picker - 用户选择组件
-
-> 平台统一的用户挑选组件，用于选择单个或多个用户，内置用户数据加载与回显逻辑
-
-## 📦 组件位置
-
-```ts
-import "@jhlc/common-core";
-```
-
-组件已全局注册，可直接在模板中使用 `<jh-user-picker />`。
-
----
-
-## 基本用法
-
-### 1️⃣ 单选用户（最常用）
-
-```vue
-<template>
-  <jh-user-picker v-model="form.userId" placeholder="请选择负责人" />
-</template>
-
-<script setup lang="ts">
-import { ref } from "vue";
-
-const form = ref({
-  userId: ""
-});
-</script>
-```
-
----
-
-### 2️⃣ 多选用户
-
-```vue
-<jh-user-picker v-model="form.userIds" multiple placeholder="请选择相关人员" />
-```
-
----
-
-## Props 属性
-
-| 参数                 | 说明                   | 类型                  | 默认值           |
-| -------------------- | ---------------------- | --------------------- | ---------------- |
-| modelValue / v-model | 绑定值                 | `string \| string[]`  | -                |
-| multiple             | 是否多选               | `boolean`             | `false`          |
-| placeholder          | 占位提示               | `string`              | `"请选择用户"`   |
-| disabled             | 是否禁用               | `boolean`             | `false`          |
-| clearable            | 是否可清空             | `boolean`             | `true`           |
-| dataType             | 返回数据类型（多选时） | `"array" \| "string"` | `"array"`        |
-| dialogTitle          | 弹窗标题               | `string`              | `"选择用户"`     |
-| dialogWidth          | 弹窗宽度               | `string`              | `"800px"`        |
-| searchPlaceholder    | 搜索框占位文本         | `string`              | `"请输入用户名"` |
-
-> **重点**: 多选时,`dataType="string"` 会返回逗号分隔的字符串,`dataType="array"` 返回数组。
-
----
-
-## Events 事件
-
-| 事件名            | 说明                     | 回调参数                              |
-| ----------------- | ------------------------ | ------------------------------------- |
-| update:modelValue | v-model 更新             | `(value: string \| string[]) => void` |
-| confirm           | 确认选择时触发           | `() => void`                          |
-| clear             | 清空时触发               | `() => void`                          |
-| blur              | 失去焦点时触发           | `() => void`                          |
-| closed            | 弹窗关闭时触发           | `() => void`                          |
-| remove            | 移除选中项时触发（多选） | `() => void`                          |
-
----
-
-## 常见场景
-
-### 场景 1：表单负责人选择
-
-```vue
-<jh-user-picker v-model="form.ownerId" placeholder="请选择负责人" />
-```
-
----
-
-### 场景 2：查询条件（多选）
-
-```vue
-<jh-user-picker v-model="query.userIds" multiple placeholder="请选择用户" />
-```
-
----
-
-### 场景 3：详情页只读展示（配合 jh-text）
-
-```vue
-<jh-text type="user" :value="detail.userId" />
-```
-
-> ⚠️ `jh-user-picker` 仅用于选择，展示请使用 `jh-text`
-
----
-
-## 与手动实现对比
-
-### 使用 jh-user-picker（推荐）
-
-```vue
-<jh-user-picker v-model="form.userId" />
-```
-
-### 手动实现（不推荐）
-
-```vue
-<el-select v-model="form.userId">
-  <el-option
-    v-for="user in userList"
-    :key="user.id"
-    :label="user.name"
-    :value="user.id"
-  />
-</el-select>
-```
-
-❌ 需要自己加载用户列表  
-❌ 需要处理回显  
-❌ 每个页面重复实现
-
----
-
-## 最佳实践
-
-### 1️⃣ 编辑 & 展示分离
-
-| 场景 | 编辑           | 展示    |
-| ---- | -------------- | ------- |
-| 用户 | jh-user-picker | jh-text |
-
----
-
-### 2️⃣ 表单中直接使用 v-model
-
-```vue
-<jh-user-picker v-model="form.userId" />
-```
-
-避免手动监听 `change` 事件
-
----
-
-### 3️⃣ 多选返回值说明
-
-```ts
-// 单选
-userId: "u001";
-
-// 多选
-userIds: ["u001", "u002"];
-```
-
----
-
-## 注意事项
-
-1. **组件内部已处理用户数据加载**
-   - 不需要手动请求接口
-   - 支持自动回显
-
-2. **仅返回用户 ID**
-   - 展示用户名称请使用 `jh-text`
-
-3. **多选时注意字段类型**
-   - 必须使用数组接收
-
----
-
-## 🎯 真实项目示例
-
-### 示例 1：新增页面
-
-```vue
-<jh-user-picker v-model="form.createUserId" />
-```
-
-### 示例 2：查询条件
-
-```vue
-<jh-user-picker v-model="query.userIds" multiple />
-```
-
----
-
-## 🚀 快速开始
-
-- **单选**：直接使用 v-model
-- **多选**：添加 `multiple`
-- **展示**：统一使用 `jh-text type="user"`
-
-**推荐作为平台统一的用户选择组件使用！**
+# jh-user-picker - 用户选择组件
+
+> 平台统一的用户挑选组件，用于选择单个或多个用户，内置用户数据加载与回显逻辑
+
+## 📦 组件位置
+
+```ts
+import "@jhlc/common-core";
+```
+
+组件已全局注册，可直接在模板中使用 `<jh-user-picker />`。
+
+---
+
+## 基本用法
+
+### 1️⃣ 单选用户（最常用）
+
+```vue
+<template>
+  <jh-user-picker v-model="form.userId" placeholder="请选择负责人" />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+
+const form = ref({
+  userId: ""
+});
+</script>
+```
+
+---
+
+### 2️⃣ 多选用户
+
+```vue
+<jh-user-picker v-model="form.userIds" multiple placeholder="请选择相关人员" />
+```
+
+---
+
+## Props 属性
+
+| 参数                 | 说明                   | 类型                  | 默认值           |
+| -------------------- | ---------------------- | --------------------- | ---------------- |
+| modelValue / v-model | 绑定值                 | `string \| string[]`  | -                |
+| multiple             | 是否多选               | `boolean`             | `false`          |
+| placeholder          | 占位提示               | `string`              | `"请选择用户"`   |
+| disabled             | 是否禁用               | `boolean`             | `false`          |
+| clearable            | 是否可清空             | `boolean`             | `true`           |
+| dataType             | 返回数据类型（多选时） | `"array" \| "string"` | `"array"`        |
+| dialogTitle          | 弹窗标题               | `string`              | `"选择用户"`     |
+| dialogWidth          | 弹窗宽度               | `string`              | `"800px"`        |
+| searchPlaceholder    | 搜索框占位文本         | `string`              | `"请输入用户名"` |
+
+> **重点**: 多选时,`dataType="string"` 会返回逗号分隔的字符串,`dataType="array"` 返回数组。
+
+---
+
+## Events 事件
+
+| 事件名            | 说明                     | 回调参数                              |
+| ----------------- | ------------------------ | ------------------------------------- |
+| update:modelValue | v-model 更新             | `(value: string \| string[]) => void` |
+| confirm           | 确认选择时触发           | `() => void`                          |
+| clear             | 清空时触发               | `() => void`                          |
+| blur              | 失去焦点时触发           | `() => void`                          |
+| closed            | 弹窗关闭时触发           | `() => void`                          |
+| remove            | 移除选中项时触发（多选） | `() => void`                          |
+
+---
+
+## 常见场景
+
+### 场景 1：表单负责人选择
+
+```vue
+<jh-user-picker v-model="form.ownerId" placeholder="请选择负责人" />
+```
+
+---
+
+### 场景 2：查询条件（多选）
+
+```vue
+<jh-user-picker v-model="query.userIds" multiple placeholder="请选择用户" />
+```
+
+---
+
+### 场景 3：详情页只读展示（配合 jh-text）
+
+```vue
+<jh-text type="user" :value="detail.userId" />
+```
+
+> ⚠️ `jh-user-picker` 仅用于选择，展示请使用 `jh-text`
+
+---
+
+## 与手动实现对比
+
+### 使用 jh-user-picker（推荐）
+
+```vue
+<jh-user-picker v-model="form.userId" />
+```
+
+### 手动实现（不推荐）
+
+```vue
+<el-select v-model="form.userId">
+  <el-option
+    v-for="user in userList"
+    :key="user.id"
+    :label="user.name"
+    :value="user.id"
+  />
+</el-select>
+```
+
+❌ 需要自己加载用户列表  
+❌ 需要处理回显  
+❌ 每个页面重复实现
+
+---
+
+## 最佳实践
+
+### 1️⃣ 编辑 & 展示分离
+
+| 场景 | 编辑           | 展示    |
+| ---- | -------------- | ------- |
+| 用户 | jh-user-picker | jh-text |
+
+---
+
+### 2️⃣ 表单中直接使用 v-model
+
+```vue
+<jh-user-picker v-model="form.userId" />
+```
+
+避免手动监听 `change` 事件
+
+---
+
+### 3️⃣ 多选返回值说明
+
+```ts
+// 单选
+userId: "u001";
+
+// 多选
+userIds: ["u001", "u002"];
+```
+
+---
+
+## 注意事项
+
+1. **组件内部已处理用户数据加载**
+   - 不需要手动请求接口
+   - 支持自动回显
+
+2. **仅返回用户 ID**
+   - 展示用户名称请使用 `jh-text`
+
+3. **多选时注意字段类型**
+   - 必须使用数组接收
+
+---
+
+## 🎯 真实项目示例
+
+### 示例 1：新增页面
+
+```vue
+<jh-user-picker v-model="form.createUserId" />
+```
+
+### 示例 2：查询条件
+
+```vue
+<jh-user-picker v-model="query.userIds" multiple />
+```
+
+---
+
+## 🚀 快速开始
+
+- **单选**：直接使用 v-model
+- **多选**：添加 `multiple`
+- **展示**：统一使用 `jh-text type="user"`
+
+**推荐作为平台统一的用户选择组件使用！**

package/files/docs/request.md

@@ -78,23 +78,32 @@ const result = await request({
 
 ## 响应数据结构
 
-request 会自动解包响应数据，直接返回 `{ code, message, data }` 格式：
+`request()` 的 response interceptor 执行 `return cloneDeep(res.data)`，直接返回 HTTP 响应体，即 `ApiResult<T>` 结构：
 
 ```typescript
-// 后端返回格式
+// ApiResult<T> 类型定义（来自 @jhlc/types）
+interface ApiResult<T = any> {
+  code: number;     // 2000 = 成功，200 也被接受（mock 常用）
+  message: string;  // 提示信息
+  data: T;          // 实际业务数据
+}
+
+// 后端返回的 HTTP 响应体（request() 直接返回这层，不再多一层 .data）
 {
-  code: 200,
+  code: 2000,
   message: "操作成功",
   data: { id: 1, name: "张三" }
 }
 
-// 使用 request 后直接拿到解包数据
+// 使用 request 后直接拿到
 const result = await request({ url: "/api/xxx", method: "get" });
-console.log(result.code);     // 200
+console.log(result.code);     // 2000
 console.log(result.message);  // "操作成功"
-console.log(result.data);     // { id: 1, name: "张三" }
+console.log(result.data);     // { id: 1, name: "张三" }（业务数据）
 ```
 
+> **与 `getAction`/`postAction` 的关系**：这些 action 函数内部调用 `request()`，返回值结构**完全相同**，类型签名为 `Promise<ApiResult<T>>`。`ApiResult<T>` 就是上面的 `{ code, message, data: T }`，两者等价。
+
 ## 常见场景
 
 ### 场景 1：列表查询
@@ -254,8 +263,8 @@ await request({ url: "/api/user/detail", method: "get", params: { id: 1 } });
 1. **自动解包**：返回 `{ code, message, data }` 格式，无需 `res.data.data`
 2. **Token 注入**：自动从 localStorage 读取 token 并添加到请求头
 3. **错误拦截**：统一处理 401/403/500 等错误，自动弹出提示
-4. **Loading 状态**：可选的全局 loading 动画
-5. **重复请求取消**：防止短时间内重复请求
+4. **双码成功**：`code: 2000`（真实后端业务码）和 `code: 200`（mock 常用值）均视为成功
+5. **i18n 支持**：自动在请求头注入当前语言（`Lang` header）
 
 ## 在组件中使用
 
@@ -326,8 +335,9 @@ try {
 2. **params vs data**：
    - `params`：URL 查询参数，适用于 GET/DELETE
    - `data`：请求体数据，适用于 POST/PUT
-3. **返回值**：直接返回解包后的数据，不是 axios 的 response 对象
+3. **返回值**：直接返回 `ApiResult<T>` = `{ code, message, data }`，不是 axios 的 response 对象（已自动解包一层）
 4. **错误处理**：request 会自动处理错误并提示，通常不需要手动 catch
+5. **mock 的 code 值**：response interceptor 同时接受 `code: 200` 和 `code: 2000` 作为成功。项目 mock 文件通常写 `code: 200`（HTTP 标准），真实后端使用业务码 `code: 2000`，两者均正常工作
 
 ## 实际案例
 
@@ -424,6 +434,11 @@ export function createFormModal(props, mode, emit) {
 ## 📌 AbstractPageQueryHook 基类内置方法
 
 > 在继承 `AbstractPageQueryHook` 的页面中，可以直接使用以下内置方法，**无需单独创建 API 层文件**。
+> 这些方法（`getAction`/`postAction`/`putAction`/`deleteAction`）也可以单独导入使用：
+> ```typescript
+> import { getAction, postAction, putAction, deleteAction } from "@jhlc/common-core/src/api/action";
+> ```
+> 返回值均为 `Promise<ApiResult<T>>`，即 `{ code: number, message: string, data: T }`，与直接调用 `request()` 完全相同。
 
 ### 可用方法一览
 

package/files/src/components/global/C_RightToolbar/data.ts

@@ -0,0 +1,228 @@
+import { ref, computed, watch, nextTick } from "vue";
+import { postAction, getAction } from "@jhlc/common-core/src/api/action";
+import Sortable from "sortablejs";
+import { deepClone } from "@/util";
+import { useI18n } from "vue-i18n";
+
+// ===== 类型定义 =====
+export interface RightToolbarProps {
+  proVisible?: boolean;
+  showSearch?: boolean;
+  columns?: any[];
+  tableId?: string;
+  initialColumns?: any[];
+  id?: string;
+  propsValue?: any[];
+  disabled?: boolean;
+  showRefreshTool?: boolean;
+  showSearchTool?: boolean;
+  showColumnTool?: boolean;
+}
+
+// ===== 组件逻辑 =====
+export function createRightToolbar(
+  props: RightToolbarProps,
+  emits: (event: string, ...args: any[]) => void,
+) {
+  const { t } = useI18n();
+
+  const transferRef = ref<any>(null);
+  const data = ref<any[]>([]);
+  const title = ref(t("设置显示字段"));
+  const open = ref(false);
+  const showFields = ref("");
+  const hideFields = ref("");
+  const defaultColumns = ref<any[]>([]);
+  const columnId = ref("");
+  const emitTemp = ref<any[]>([]);
+  const submitLoading = ref(false);
+
+  const modelValue = ref<any[]>([]);
+  watch(
+    () => props.propsValue,
+    (newVal) => {
+      modelValue.value = newVal ?? [];
+    },
+    { immediate: true },
+  );
+
+  const columnsProp = computed(() => props.columns);
+  const showSearchProp = computed(() => props.showSearch);
+
+  const temp = computed(() => data.value.filter((item) => item.visible));
+
+  // 搜索
+  function toggleSearch() {
+    emits("update:showSearch", !props.showSearch);
+  }
+
+  // 刷新
+  function refresh() {
+    emits("queryTable");
+  }
+
+  // 关闭弹窗
+  const closeDialog = () => {
+    initColumns();
+  };
+
+  // 穿梭变化
+  function dataChange(val: any[]) {
+    if (val) {
+      data.value.forEach((item) => {
+        const index = val.findIndex((ele) => ele === item.key);
+        item.visible = index === -1;
+      });
+    }
+  }
+
+  // 打开显隐列dialog
+  function showColumn() {
+    open.value = true;
+    data.value = [];
+    defaultColumns.value = [];
+    props.columns?.forEach((item) => {
+      defaultColumns.value.push(deepClone(item));
+      data.value.push(deepClone(item));
+    });
+    nextTick(() => {
+      const transfer = transferRef.value.$el;
+      const leftPanel = transfer
+        .getElementsByClassName("el-transfer-panel")[0]
+        .getElementsByClassName("el-transfer-panel__body")[0];
+      const leftEl = leftPanel.getElementsByClassName(
+        "el-transfer-panel__list",
+      )[0];
+      Sortable.create(leftEl, {
+        onEnd: (evt: any) => {
+          const { oldIndex, newIndex } = evt;
+          const visible = data.value.filter((item) => item.visible);
+          const [moved] = visible.splice(oldIndex, 1);
+          visible.splice(newIndex, 0, moved);
+          const hidden = data.value.filter((item) => !item.visible);
+          data.value = [...visible, ...hidden];
+        },
+      });
+    });
+  }
+
+  // 恢复工具
+  function recoverTool(recoverData: any[]) {
+    const dataTemp: any[] = [];
+    const modelValueTemp: any[] = [];
+    recoverData.forEach((item) => {
+      dataTemp.push(deepClone(item));
+      if (!item.visible) modelValueTemp.push(item.key);
+    });
+    data.value = dataTemp;
+    modelValue.value = modelValueTemp;
+  }
+
+  function initColumns() {
+    recoverTool(defaultColumns.value);
+  }
+
+  function clearValue() {
+    recoverTool(props.initialColumns ?? []);
+  }
+
+  function cancelBtn() {
+    initColumns();
+    open.value = false;
+  }
+
+  function submitBtn() {
+    showFields.value = "";
+    hideFields.value = "";
+    temp.value.forEach((item) => {
+      showFields.value += `${item.key},`;
+    });
+    hideFields.value = modelValue.value.join();
+    const paramsList = {
+      id: columnId.value || props.id,
+      tableId: props.tableId,
+      showFields: showFields.value,
+      hideFields: hideFields.value,
+    };
+    submitLoading.value = true;
+    postAction("system/pageShowFields/saveOrUpdate", paramsList)
+      .then((res: any) => {
+        temp.value.forEach((item) => emitTemp.value.push(item));
+        data.value.forEach((item) => {
+          if (!item.visible) emitTemp.value.push(item);
+        });
+        columnId.value = res.data.id;
+        emits("update:columns", emitTemp.value);
+        emits("update:propsValue", modelValue.value);
+        emitTemp.value = [];
+      })
+      .catch(() => initColumns())
+      .finally(() => {
+        submitLoading.value = false;
+        open.value = false;
+      });
+  }
+
+  function getColumns(columnsInfo: any) {
+    const _columnsInfo = deepClone(columnsInfo);
+    _columnsInfo.propsValue = [];
+    return getAction(
+      `/system/pageShowFields/getByTableIdAndUserNo?tableId=${_columnsInfo.tableId}`,
+    ).then((res: any) => {
+      if (res.data) {
+        _columnsInfo.id = res.data.id;
+        let showArr: string[] | undefined;
+        if (res.data.showFields) showArr = res.data.showFields.split(",");
+        let hideArr: string[] | undefined;
+        if (res.data.hideFields) hideArr = res.data.hideFields.split(",");
+
+        let flag: any[] = [];
+        if (showArr) {
+          flag = showArr.reduce((acc: any[], key: string) => {
+            const value = _columnsInfo.columns.find((v: any) => v.key === key);
+            if (value) acc.push(value);
+            return acc;
+          }, []);
+        }
+        const result: any[] = [...new Set(flag.concat(_columnsInfo.columns))];
+        _columnsInfo.columns = result;
+
+        _columnsInfo.columns.forEach((item: any) => {
+          if (showArr) {
+            item.visible = showArr.includes(item.key) ? true : item.visible;
+          }
+          if (hideArr) {
+            item.visible = hideArr.includes(item.key) ? false : item.visible;
+          }
+        });
+
+        if (hideArr) {
+          hideArr.forEach((item: string) => _columnsInfo.propsValue.push(item));
+        }
+        return _columnsInfo;
+      }
+    });
+  }
+
+  return {
+    transferRef,
+    data,
+    title,
+    open,
+    modelValue,
+    columnsProp,
+    showSearchProp,
+    temp,
+    submitLoading,
+    toggleSearch,
+    refresh,
+    closeDialog,
+    dataChange,
+    showColumn,
+    initColumns,
+    clearValue,
+    cancelBtn,
+    submitBtn,
+    getColumns,
+  };
+}