@agile-team/wl-skills-kit 1.0.0

package/files/docs/jh-picker.md

@@ -0,0 +1,218 @@
+# jh-picker - 通用关联挑选组件
+
+> 平台统一的通用数据挑选组件，适用于需要从某一业务数据源中选择一条或多条数据的场景，常用于关联单据、基础资料等
+
+## 📦 组件位置
+
+```ts
+import "@jhlc/common-core";
+```
+
+组件已全局注册，可直接在模板中使用 `<jh-picker />`。
+
+---
+
+## 基本用法
+
+### 1️⃣ 单选关联数据（最常用）
+
+```vue
+<template>
+  <jh-picker
+    v-model="form.customerId"
+    picker-type="customer"
+    placeholder="请选择客户"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+
+const form = ref({
+  customerId: ""
+});
+</script>
+```
+
+---
+
+### 2️⃣ 多选关联数据
+
+```vue
+<jh-picker
+  v-model="form.productIds"
+  picker-type="product"
+  multiple
+  placeholder="请选择商品"
+/>
+```
+
+---
+
+## Props 属性
+
+| 参数                 | 说明                             | 类型                                                                     | 默认值                |
+| -------------------- | -------------------------------- | ------------------------------------------------------------------------ | --------------------- |
+| modelValue / v-model | 绑定值                           | `string \| string[]`                                                     | -                     |
+| pickerType           | 选择器类型（业务标识）           | `string`                                                                 | -                     |
+| single               | 是否单选（与 multiple 相反）     | `boolean`                                                                | `true`                |
+| multiple             | 是否多选                         | `boolean`                                                                | `false`               |
+| placeholder          | 占位提示                         | `string`                                                                 | `"请选择"`            |
+| disabled             | 是否禁用                         | `boolean`                                                                | `false`               |
+| clearable            | 是否可清空                       | `boolean`                                                                | `true`                |
+| dataType             | 返回数据类型（多选时）           | `"array" \| "string"`                                                    | `"array"`             |
+| showType             | 显示类型                         | `"" \| "button"`                                                         | `""`                  |
+| showLabel            | 按钮文本（showType="button" 时） | `string`                                                                 | -                     |
+| buttonType           | 按钮类型                         | `"default" \| "primary" \| "success" \| "info" \| "warning" \| "danger"` | `"default"`           |
+| buttonIcon           | 按钮图标                         | `"Search" \| "Edit" \| "Delete" \| "Plus" \| "Refresh"`                  | -                     |
+| title                | 弹窗标题                         | `string`                                                                 | -                     |
+| width                | 弹窗宽度                         | `string`                                                                 | `"800px"`             |
+| listUrl              | 列表查询接口                     | `string`                                                                 | -                     |
+| listByIdsUrl         | 根据ID查询接口（回显）           | `string`                                                                 | -                     |
+| query                | 查询条件配置                     | `Array`                                                                  | -                     |
+| columns              | 表格列配置                       | `Array`                                                                  | -                     |
+| valueAttr            | 值字段路径                       | `string[] \| string`                                                     | `["id"]`              |
+| labelAttr            | 标签字段路径                     | `string[] \| string`                                                     | `["name"]`            |
+| dataAttr             | 数据字段路径                     | `string[] \| string`                                                     | `["data", "records"]` |
+
+> **重点**: `pickerType` 必须是平台配置过的类型,否则需要手动配置 `listUrl`、`query`、`columns` 等参数。
+
+---
+
+## Events 事件
+
+| 事件名            | 说明           | 回调参数                              |
+| ----------------- | -------------- | ------------------------------------- |
+| update:modelValue | v-model 更新   | `(value: string \| string[]) => void` |
+| change            | 选择变化时触发 | `() => void`                          |
+| ok                | 确认选择时触发 | `() => void`                          |
+| clear             | 清空时触发     | `() => void`                          |
+
+---
+
+## 常见场景
+
+### 场景 1：选择关联客户
+
+```vue
+<jh-picker v-model="form.customerId" picker-type="customer" />
+```
+
+---
+
+### 场景 2：选择关联单据
+
+```vue
+<jh-picker v-model="form.orderId" picker-type="order" />
+```
+
+---
+
+### 场景 3：多选关联基础资料
+
+```vue
+<jh-picker v-model="form.materialIds" picker-type="material" multiple />
+```
+
+---
+
+### 场景 4：详情页展示（配合 jh-text）
+
+```vue
+<jh-text :value="detail.customerName" />
+```
+
+> ⚠️ `jh-picker` 仅负责选择，展示请使用文本组件
+
+---
+
+## 与手动实现对比
+
+### 使用 jh-picker（推荐）
+
+```vue
+<jh-picker v-model="form.customerId" picker-type="customer" />
+```
+
+### 手动实现（不推荐）
+
+```vue
+<el-input v-model="form.customerName" @click="openDialog" readonly />
+```
+
+❌ 需要自己实现弹窗  
+❌ 需要处理列表查询  
+❌ 需要维护回填逻辑
+
+---
+
+## 最佳实践
+
+### 1️⃣ pickerType 必须语义清晰
+
+```vue
+<jh-picker picker-type="customer" />
+<jh-picker picker-type="product" />
+```
+
+确保不同业务类型对应不同选择器配置
+
+---
+
+### 2️⃣ 编辑 & 展示分离
+
+| 场景     | 编辑      | 展示               |
+| -------- | --------- | ------------------ |
+| 关联数据 | jh-picker | jh-text / 普通文本 |
+
+---
+
+### 3️⃣ 多选返回值说明
+
+```ts
+// 单选
+customerId: "c001";
+
+// 多选
+productIds: ["p001", "p002"];
+```
+
+---
+
+## 注意事项
+
+1. **pickerType 由平台统一配置**
+   - 不可随意填写
+   - 必须是平台已支持的类型
+
+2. **组件仅返回关联 ID**
+   - 其他字段需自行处理或由后端返回
+
+3. **多选注意字段类型**
+   - 必须使用数组接收
+
+---
+
+## 🎯 真实项目示例
+
+### 示例 1：销售订单选择客户
+
+```vue
+<jh-picker v-model="form.customerId" picker-type="customer" />
+```
+
+### 示例 2：采购单选择商品
+
+```vue
+<jh-picker v-model="form.productIds" picker-type="product" multiple />
+```
+
+---
+
+## 🚀 快速开始
+
+1. 确定业务类型（pickerType）
+2. 使用 v-model 绑定 ID
+3. 展示统一使用文本组件
+
+**推荐作为平台统一的通用关联选择组件使用！**

package/files/docs/jh-select.md

@@ -0,0 +1,148 @@
+# jh-select - 字典下拉选择组件
+
+> 集成平台数据字典的下拉选择组件，只需传入字典名称即可自动加载选项，统一字典使用方式
+
+## 📦 组件位置
+
+```ts
+import "@jhlc/common-core";
+```
+
+组件已全局注册，可直接在模板中使用 `<jh-select />`。
+
+## 基本用法
+
+### 根据字典名称加载
+
+```vue
+<template>
+  <jh-select
+    v-model="form.status"
+    dict="order_status"
+    placeholder="请选择订单状态"
+    clearable
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+
+const form = ref({
+  status: ""
+});
+</script>
+```
+
+## Props 属性
+
+| 参数                 | 说明                      | 类型                                                     | 默认值     |
+| -------------------- | ------------------------- | -------------------------------------------------------- | ---------- |
+| modelValue / v-model | 绑定值                    | `string \| number \| Array<string \| number> \| boolean` | -          |
+| dict                 | 字典名称（平台字典 code） | `string`                                                 | -          |
+| items                | 静态数据选项              | `Array<{label: string, value: any}>`                     | `[]`       |
+| placeholder          | 占位提示                  | `string`                                                 | `"请选择"` |
+| clearable            | 是否可清空                | `boolean`                                                | `true`     |
+| disabled             | 是否禁用                  | `boolean`                                                | `false`    |
+| multiple             | 是否多选                  | `boolean`                                                | `false`    |
+| filterable           | 是否可搜索                | `boolean`                                                | `false`    |
+| datasourceType       | 数据源类型                | `"static" \| "interface"`                                | `"static"` |
+| multiDataFormat      | 多选时的数据格式          | `"string" \| "array"`                                    | `"array"`  |
+| collapseTag          | 多选时是否折叠 Tag        | `boolean`                                                | `false`    |
+| teleported           | 是否将下拉面板插入 body   | `boolean`                                                | `true`     |
+
+> **重点**: 当 `dict` 属性存在时,组件会自动加载对应字典数据,无需手动设置 `items`。
+
+## Events 事件
+
+| 事件名            | 说明         | 回调参数          |
+| ----------------- | ------------ | ----------------- |
+| change            | 选中值变化   | `(value) => void` |
+| update:modelValue | v-model 更新 | `(value) => void` |
+
+## 常见场景
+
+### 场景 1：列表查询条件
+
+```vue
+<jh-select v-model="query.status" dict="order_status" placeholder="订单状态" />
+```
+
+### 场景 2：表单编辑
+
+```vue
+<jh-select v-model="form.type" dict="order_type" :disabled="isView" />
+```
+
+### 场景 3：多选字典
+
+```vue
+<jh-select v-model="form.tags" dict="order_tag" multiple />
+```
+
+### 场景 4：BaseQuery 配置式用法（推荐）
+
+```ts
+// data.ts 查询项配置
+export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
+  {
+    name: "orderStatus",
+    label: "操作类型",
+    placeholder: "请选择操作类型",
+    component: () => {
+      return {
+        tag: "jh-select",
+        // 方式一：静态数据
+        items: [
+          { label: "是", value: 1 },
+          { label: "否", value: 0 }
+        ]
+      };
+    }
+  },
+  {
+    name: "status",
+    label: "状态",
+    logicType: BusLogicDataType.dict,
+    logicValue: "order_status" // 字典 code
+    // 方式二：使用字典数据（会自动加载）
+  }
+];
+```
+
+### 场景 5：静态 items 方式
+
+```vue
+<jh-select
+  v-model="form.gender"
+  :items="[
+    { label: '男', value: 1 },
+    { label: '女', value: 2 }
+  ]"
+  placeholder="请选择性别"
+/>
+```
+
+---
+
+## 最佳实践
+
+1. **始终使用 dict 属性**
+   - 不要手动写 options
+   - 保证字典来源统一
+
+2. **配合 jh-text 使用**
+   - 列表展示用 `jh-text`
+   - 表单编辑用 `jh-select`
+
+3. **字典值以字符串为主**
+   - 避免 number/string 混用
+
+## 注意事项
+
+- 字典数据来自平台缓存
+- 字典名称必须是平台已配置的 code
+- 多选时返回数组
+
+---
+
+✅ **推荐作为平台统一的字典下拉组件使用**

package/files/docs/jh-text.md

@@ -0,0 +1,248 @@
+# jh-text - 文本展示组件
+
+> 统一的文本展示组件，内置平台字典、用户、部门的自动翻译能力，用于列表、详情等只读场景
+
+## 📦 组件位置
+
+```ts
+import "@jhlc/common-core";
+```
+
+组件已全局注册，可直接在模板中使用 `<jh-text />`。
+
+---
+
+## 基本用法
+
+### 1️⃣ 字典文本展示（最常用）
+
+```vue
+<template>
+  <jh-text dict="order_status" :value="row.status" />
+</template>
+```
+
+> 根据字典 code + value 自动翻译显示文本
+
+---
+
+### 2️⃣ 用户名称展示
+
+```vue
+<jh-text type="user" :value="row.createUserId" />
+```
+
+---
+
+### 3️⃣ 部门名称展示
+
+```vue
+<jh-text type="dept" :value="row.deptId" />
+```
+
+---
+
+### 4️⃣ 普通文本展示
+
+```vue
+<jh-text :value="row.remark" />
+```
+
+---
+
+## Props 属性
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| content | 需要展示的值（优先级高于 value） | `string \| number \| Date \| Array` | `""` |
+| value | 需要展示的值（与Content二选一） | `string \| number \| string[]` | - |
+| dict | 字典名称（平台字典 code） | `string` | - |
+| type | 文本类型 | `"text" \| "dict" \| "user" \| "dept"` | `"text"` |
+| logicType | 逻辑类型（用于自动识别） | `BusLogicDataType` | - |
+| logicValue | 逻辑值（字典code/用户/部门） | `string` | - |
+| separator | 多值分隔符 | `string` | `"、"` |
+| emptyText | 空值显示文本 | `string` | `"-"` |
+| format | 文本格式 | `"default" \| "ellipsis" \| "html"` | `"default"` |
+| rows | 多行显示时的行数 | `number` | `1` |
+| fontSize | 字体大小 | `"extra-small" \| "small" \| "base" \| "medium" \| "large" \| "extra-large"` | - |
+| fontWeight | 字体粗细 | `"light" \| "regular" \| "medium" \| "semi"` | - |
+
+> **提示**: 
+> - `dict` 传入时,会自动设置 `type="dict"`
+> - 同时使用 `logicType` 和 `logicValue` 可以实现自动翻译
+
+---
+
+## 支持类型说明
+
+| type 值 | 说明 |
+| --- | --- |
+| text | 普通文本（默认） |
+| dict | 字典翻译 |
+| user | 用户名称 |
+| dept | 部门名称 |
+
+> 当传入 `dict` 时，`type` 可省略
+
+---
+
+## 常见场景
+
+### 场景 1：表格字典列展示（推荐）
+
+```vue
+<el-table-column label="订单状态">
+  <template #default="{ row }">
+    <jh-text dict="order_status" :value="row.status" />
+  </template>
+</el-table-column>
+```
+
+✅ **统一字典展示**  
+✅ **避免每个页面手动转换**
+
+---
+
+### 场景 2：用户/部门字段展示
+
+```vue
+<jh-text type="user" :value="row.createUserId" />
+<jh-text type="dept" :value="row.deptId" />
+```
+
+---
+
+### 场景 3：详情页只读展示
+
+```vue
+<el-descriptions-item label="订单状态">
+  <jh-text dict="order_status" :value="detail.status" />
+</el-descriptions-item>
+```
+
+---
+
+### 场景 4：多值展示
+
+```vue
+<jh-text
+  dict="order_tag"
+  :value="row.tags"
+  separator=" / "
+/>
+```
+
+### 场景 5：BaseDetail 配置式用法
+
+```ts
+// data.ts 详情项配置
+export const detailItemsConfig: BaseFormDetailDesc[] = [
+  {
+    name: "status",
+    label: "状态",
+    logicType: BusLogicDataType.dict,
+    logicValue: "order_status"
+    // 会自动渲染为 jh-text 并翻译字典
+  },
+  {
+    name: "createUserId",
+    label: "创建人",
+    logicType: BusLogicDataType.user,
+    logicValue: "userId"
+    // 会自动翻译用户名
+  }
+];
+```
+
+---
+
+## 与手动处理对比
+
+### 使用 jh-text（推荐）
+
+```vue
+<jh-text dict="order_status" :value="row.status" />
+```
+
+### 手动处理（不推荐）
+
+```vue
+{{ getDictLabel("order_status", row.status) }}
+```
+
+❌ 依赖工具函数  
+❌ 每个页面重复实现  
+❌ 不利于统一规范
+
+---
+
+## 最佳实践
+
+### 1️⃣ 列表展示统一使用 jh-text
+
+- 字典值
+- 用户 / 部门 ID
+- 多选值
+
+```vue
+<jh-text ... />
+```
+
+---
+
+### 2️⃣ 表单编辑 + 展示组件配套使用
+
+| 场景 | 编辑 | 展示 |
+| --- | --- | --- |
+| 字典 | jh-select | jh-text |
+| 用户 | jh-user-picker | jh-text |
+| 部门 | jh-dept-picker | jh-text |
+
+---
+
+### 3️⃣ 空值兜底处理
+
+```vue
+<jh-text :value="row.remark" empty-text="暂无" />
+```
+
+---
+
+## 注意事项
+
+1. **仅用于展示**
+   - 不支持编辑
+   - 不触发任何 change 事件
+
+2. **字典值必须合法**
+   - value 必须存在于字典中
+   - 否则显示 `emptyText`
+
+3. **多值类型**
+   - value 为数组或逗号分隔字符串均可
+
+---
+
+## 🎯 真实项目示例
+
+### 示例 1：列表页
+
+```vue
+<jh-text dict="order_status" :value="row.status" />
+```
+
+### 示例 2：详情页
+
+```vue
+<jh-text type="user" :value="detail.createUserId" />
+```
+
+---
+
+## 🚀 快速开始
+
+- **字典展示**：直接传 `dict`
+- **用户/部门**：使用 `type`
+- **空值兜底**：配置 `emptyText`
+
+**推荐作为平台统一的文本展示组件使用！**