@agile-team/wl-skills-kit 1.0.0

package/files/docs/jh-date-range.md

@@ -0,0 +1,257 @@
+# jh-date-range - 日期范围选择组件
+
+> 平台统一的日期范围选择组件，封装常用日期范围选择交互与默认格式，适用于查询条件、统计分析等需要选择开始/结束日期的场景
+
+## 📦 组件位置
+
+```ts
+import "@jhlc/common-core";
+```
+
+组件已全局注册，可直接在模板中使用 `<jh-date-range />`。
+
+---
+
+## 基本用法
+
+### 1️⃣ 选择日期范围（最常用）
+
+```vue
+<template>
+  <jh-date-range v-model="query.dateRange" placeholder="请选择日期范围" />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+
+const query = ref({
+  dateRange: []
+});
+</script>
+```
+
+---
+
+### 2️⃣ 查询条件中使用（推荐）
+
+```vue
+<jh-date-range
+  v-model="query.createDateRange"
+  placeholder="创建日期"
+  clearable
+/>
+```
+
+---
+
+## Props 属性
+
+| 参数                            | 说明                         | 类型                                             | 默认值             |
+| ------------------------------- | ---------------------------- | ------------------------------------------------ | ------------------ |
+| modelValue / v-model            | 绑定值（开始/结束数组）      | `Array<string \| Date>`                          | `[]`               |
+| beginValue / v-model:beginValue | 开始日期（可拆分绑定）       | `string \| Date`                                 | -                  |
+| endValue / v-model:endValue     | 结束日期（可拆分绑定）       | `string \| Date`                                 | -                  |
+| placeholder                     | 占位提示                     | `string`                                         | `"请选择日期范围"` |
+| startPlaceholder                | 开始日期占位                 | `string`                                         | `"开始日期"`       |
+| endPlaceholder                  | 结束日期占位                 | `string`                                         | `"结束日期"`       |
+| type                            | 范围选择器类型               | `"daterange" \| "monthrange" \| "datetimerange"` | `"daterange"`      |
+| format                          | 绑定值格式（返回给 v-model） | `string`                                         | `"YYYY-MM-DD"`     |
+| showFormat                      | 显示格式                     | `string`                                         | `"YYYY-MM-DD"`     |
+| rangeSeparator                  | 分隔符                       | `string`                                         | `"至"`             |
+| disabled                        | 是否禁用                     | `boolean`                                        | `false`            |
+| clearable                       | 是否可清空                   | `boolean`                                        | `true`             |
+
+> **新增提示**: 除了使用 `v-model` 绑定数组外,还可以使用 `v-model:beginValue` 和 `v-model:endValue` 分别绑定开始和结束日期,这在某些场景下更加灵活。
+
+---
+
+## Events 事件
+
+| 事件名            | 说明               | 回调参数                                 |
+| ----------------- | ------------------ | ---------------------------------------- |
+| update:modelValue | v-model 更新时触发 | `(value: Array<string \| Date>) => void` |
+| update:beginValue | 开始日期更新时触发 | `(value: string \| Date) => void`        |
+| update:endValue   | 结束日期更新时触发 | `(value: string \| Date) => void`        |
+| blur              | 失去焦点时触发     | `() => void`                             |
+
+---
+
+## 常见场景
+
+### 场景 1：列表查询时间范围（推荐）
+
+```vue
+<jh-date-range v-model="query.bizDateRange" placeholder="业务日期" />
+```
+
+---
+
+### 场景 2：统计报表筛选
+
+```vue
+<jh-date-range v-model="query.statRange" placeholder="统计区间" />
+```
+
+---
+
+### 场景 3：BaseQuery 配置式用法（推荐）
+
+```ts
+// data.ts 查询项配置
+export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
+  {
+    name: "createDateTime",
+    startName: "createDateTimeStart", // 开始字段
+    endName: "createDateTimeEnd", // 结束字段
+    label: "创建日期",
+    component: () => {
+      return {
+        tag: "jh-date",
+        type: "daterange",
+        rangeSeparator: "至",
+        showFormat: "YYYY-MM-DD",
+        valueFormat: "YYYY-MM-DD"
+      };
+    }
+  }
+];
+
+// 使用时会自动拆分为 startName 和 endName 两个字段
+// query.createDateTimeStart = "2026-01-01"
+// query.createDateTimeEnd = "2026-01-31"
+```
+
+### 场景 4：与后端接口参数映射
+
+```ts
+// v-model 方式
+query.dateRange = ["2026-01-01", "2026-01-31"]
+
+// 请求参数建议拆分传递
+params: {
+  startDate: query.dateRange?.[0],
+  endDate: query.dateRange?.[1]
+}
+
+// 或使用 beginValue/endValue 方式
+query.beginDate = "2026-01-01"
+query.endDate = "2026-01-31"
+
+// 请求参数直接使用
+params: {
+  startDate: query.beginDate,
+  endDate: query.endDate
+}
+```
+
+---
+
+## 与 el-date-picker 对比
+
+### 使用 jh-date-range（推荐）
+
+```vue
+<jh-date-range v-model="query.dateRange" />
+```
+
+✅ 统一默认格式  
+✅ 简化配置  
+✅ 风格一致
+
+### 使用 el-date-picker（不推荐）
+
+```vue
+<el-date-picker
+  v-model="query.dateRange"
+  type="daterange"
+  value-format="YYYY-MM-DD"
+  format="YYYY-MM-DD"
+  range-separator="至"
+  start-placeholder="开始日期"
+  end-placeholder="结束日期"
+/>
+```
+
+❌ 配置繁琐  
+❌ 每处都要重复写默认格式  
+❌ 风格不统一
+
+---
+
+## 最佳实践
+
+### 1️⃣ 统一返回字符串格式（强烈推荐）
+
+```vue
+<jh-date-range v-model="query.dateRange" value-format="YYYY-MM-DD" />
+```
+
+避免 Date / string 混用，接口参数更稳定
+
+---
+
+### 2️⃣ 查询条件建议 always clearable
+
+```vue
+<jh-date-range v-model="query.range" clearable />
+```
+
+---
+
+### 3️⃣ 请求参数建议拆分传递
+
+```ts
+const [startDate, endDate] = query.value.dateRange || [];
+request({
+  url: "/api/list",
+  params: { startDate, endDate }
+});
+```
+
+---
+
+### 4️⃣ 与单日期选择区分使用
+
+- 单个日期：`jh-date`
+- 日期范围：`jh-date-range`
+
+---
+
+## 注意事项
+
+1. **v-model 为数组**
+   - 必须使用数组字段接收
+   - 推荐默认 `[]`
+
+2. **valueFormat 决定返回类型**
+   - 默认 `"YYYY-MM-DD"` 字符串数组
+   - 不建议返回 Date（容易引入时区/格式问题）
+
+3. **后端字段建议统一**
+   - 强烈建议后端使用 `startDate/endDate` 两个字段接收
+
+---
+
+## 🎯 真实项目示例
+
+### 示例 1：列表查询
+
+```vue
+<jh-date-range v-model="query.createDateRange" />
+```
+
+### 示例 2：报表筛选
+
+```vue
+<jh-date-range v-model="query.statRange" />
+```
+
+---
+
+## 🚀 快速开始
+
+1. 使用数组字段绑定 v-model（如 `dateRange`）
+2. 默认返回 `"YYYY-MM-DD"` 字符串数组
+3. 请求参数拆分成 start / end 传递
+
+**推荐作为平台统一的日期范围选择组件使用！**

package/files/docs/jh-date.md

@@ -0,0 +1,222 @@
+# jh-date - 日期选择组件
+
+> 平台统一的日期选择组件，封装常用日期选择交互与默认格式，适用于表单、查询条件等需要选择单个日期的场景
+
+## 📦 组件位置
+
+```ts
+import "@jhlc/common-core";
+```
+
+组件已全局注册，可直接在模板中使用 `<jh-date />`。
+
+---
+
+## 基本用法
+
+### 1️⃣ 选择单个日期（最常用）
+
+```vue
+<template>
+  <jh-date v-model="form.date" placeholder="请选择日期" />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+
+const form = ref({
+  date: ""
+});
+</script>
+```
+
+---
+
+### 2️⃣ 查询条件使用
+
+```vue
+<jh-date v-model="query.bizDate" placeholder="业务日期" clearable />
+```
+
+---
+
+## Props 属性
+
+| 参数                 | 说明                         | 类型                                    | 默认值         |
+| -------------------- | ---------------------------- | --------------------------------------- | -------------- |
+| modelValue / v-model | 绑定值                       | `string \| Date`                        | -              |
+| placeholder          | 占位提示                     | `string`                                | `"请选择日期"` |
+| type                 | 日期类型                     | `"date" \| "week" \| "month" \| "year"` | `"date"`       |
+| format               | 绑定值格式（返回给 v-model） | `string`                                | `"YYYY-MM-DD"` |
+| showFormat           | 显示格式                     | `string`                                | `"YYYY-MM-DD"` |
+| disabled             | 是否禁用                     | `boolean`                               | `false`        |
+| clearable            | 是否可清空                   | `boolean`                               | `true`         |
+| teleported           | 是否将下拉面板插入 body      | `boolean`                               | `true`         |
+
+> **提示**: `valueFormat` 为 Element Plus 原生属性,此处统一使用 `format` 属性代替,控制返回值格式。
+
+---
+
+## Events 事件
+
+| 事件名            | 说明           | 回调参数          |
+| ----------------- | -------------- | ----------------- |
+| change            | 日期变化时触发 | `(value) => void` |
+| update:modelValue | v-model 更新   | `(value) => void` |
+
+---
+
+## 常见场景
+
+### 场景 1：表单录入日期
+
+```vue
+<jh-date v-model="form.deliveryDate" placeholder="请选择交期" />
+```
+
+---
+
+### 场景 2：列表查询日期
+
+```vue
+<jh-date v-model="query.createDate" placeholder="创建日期" />
+```
+
+---
+
+### 场景 3：详情页日期展示（配合 jh-text / 普通文本）
+
+```vue
+<span>{{ detail.bizDate }}</span>
+```
+
+> ⚠️ `jh-date` 仅用于选择，详情展示建议直接展示字符串或统一格式化后展示
+
+---
+
+### 场景 3：BaseQuery 配置式用法
+
+```ts
+// data.ts 查询项配置
+export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
+  {
+    name: "deliveryDate",
+    label: "交期日期",
+    component: () => {
+      return {
+        tag: "jh-date",
+        type: "date",
+        showFormat: "YYYY-MM-DD",
+        valueFormat: "YYYY-MM-DD" // 或使用 format
+      };
+    }
+  },
+  {
+    name: "month",
+    label: "月份",
+    component: () => {
+      return {
+        tag: "jh-date",
+        type: "month",
+        showFormat: "YYYY-MM",
+        valueFormat: "YYYY-MM"
+      };
+    }
+  }
+];
+```
+
+---
+
+## 与 el-date-picker 对比
+
+### 使用 jh-date（推荐）
+
+```vue
+<jh-date v-model="form.date" />
+```
+
+✅ 统一默认格式  
+✅ 简化 props 配置  
+✅ 风格一致
+
+### 使用 el-date-picker（不推荐）
+
+```vue
+<el-date-picker
+  v-model="form.date"
+  type="date"
+  value-format="YYYY-MM-DD"
+  format="YYYY-MM-DD"
+/>
+```
+
+❌ 每处都要重复配置格式  
+❌ 样式与交互不统一
+
+---
+
+## 最佳实践
+
+### 1️⃣ 统一返回字符串格式
+
+推荐保持 `valueFormat="YYYY-MM-DD"`，避免 Date / string 混用：
+
+```vue
+<jh-date v-model="form.date" value-format="YYYY-MM-DD" />
+```
+
+---
+
+### 2️⃣ 查询条件优先可清空
+
+```vue
+<jh-date v-model="query.date" clearable />
+```
+
+---
+
+### 3️⃣ 与日期范围选择区分使用
+
+- 单个日期：`jh-date`
+- 日期范围：`jh-date-range`
+
+---
+
+## 注意事项
+
+1. **v-model 返回值取决于 valueFormat**
+   - 默认返回 `"YYYY-MM-DD"` 字符串
+   - 若不配置可能返回 Date（取决于组件封装）
+
+2. **后端字段格式建议统一**
+   - 推荐后端/前端统一使用 `"YYYY-MM-DD"`
+
+3. **不要在不同页面混用格式**
+   - 避免接口参数混乱
+
+---
+
+## 🎯 真实项目示例
+
+### 示例 1：订单交期
+
+```vue
+<jh-date v-model="form.deliveryDate" />
+```
+
+### 示例 2：查询条件
+
+```vue
+<jh-date v-model="query.bizDate" clearable />
+```
+
+---
+
+## 🚀 快速开始
+
+1. 直接使用 v-model 绑定字段
+2. 默认返回 `"YYYY-MM-DD"` 字符串
+3. 范围选择使用 `jh-date-range`
+
+**推荐作为平台统一的单日期选择组件使用！**

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

@@ -0,0 +1,190 @@
+# jh-dept-picker - 部门选择组件
+
+> 平台统一的部门挑选组件，用于选择单个或多个部门，内置部门树数据加载与回显逻辑
+
+## 📦 组件位置
+
+```ts
+import "@jhlc/common-core";
+```
+
+组件已全局注册，可直接在模板中使用 `<jh-dept-picker />`。
+
+---
+
+## 基本用法
+
+### 1️⃣ 单选部门（最常用）
+
+```vue
+<template>
+  <jh-dept-picker v-model="form.deptId" placeholder="请选择部门" />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+
+const form = ref({
+  deptId: ""
+});
+</script>
+```
+
+---
+
+### 2️⃣ 多选部门
+
+```vue
+<jh-dept-picker v-model="form.deptIds" multiple placeholder="请选择相关部门" />
+```
+
+---
+
+## Props 属性
+
+| 参数                 | 说明                   | 类型                  | 默认值             |
+| -------------------- | ---------------------- | --------------------- | ------------------ |
+| modelValue / v-model | 绑定值                 | `string \| string[]`  | -                  |
+| multiple             | 是否多选               | `boolean`             | `false`            |
+| placeholder          | 占位提示               | `string`              | `"请选择部门"`     |
+| disabled             | 是否禁用               | `boolean`             | `false`            |
+| clearable            | 是否可清空             | `boolean`             | `true`             |
+| checkStrictly        | 父子是否不关联         | `boolean`             | `false`            |
+| dataType             | 返回数据类型（多选时） | `"array" \| "string"` | `"array"`          |
+| dialogTitle          | 弹窗标题               | `string`              | `"选择部门"`       |
+| dialogWidth          | 弹窗宽度               | `string`              | `"600px"`          |
+| searchPlaceholder    | 搜索框占位文本         | `string`              | `"请输入部门名称"` |
+
+> **重点**:
+>
+> - 默认父子关联，选中父节点会自动选中子节点
+> - `checkStrictly=true` 时,父子不互相关联
+
+---
+
+## Events 事件
+
+| 事件名            | 说明                     | 回调参数                              |
+| ----------------- | ------------------------ | ------------------------------------- |
+| update:modelValue | v-model 更新             | `(value: string \| string[]) => void` |
+| confirm           | 确认选择时触发           | `() => void`                          |
+| clear             | 清空时触发               | `() => void`                          |
+| closed            | 弹窗关闭时触发           | `() => void`                          |
+| remove            | 移除选中项时触发（多选） | `() => void`                          |
+
+---
+
+## 常见场景
+
+### 场景 1：表单部门选择
+
+```vue
+<jh-dept-picker v-model="form.deptId" placeholder="请选择所属部门" />
+```
+
+---
+
+### 场景 2：查询条件（多选）
+
+```vue
+<jh-dept-picker v-model="query.deptIds" multiple placeholder="请选择部门" />
+```
+
+---
+
+### 场景 3：详情页部门展示（配合 jh-text）
+
+```vue
+<jh-text type="dept" :value="detail.deptId" />
+```
+
+> ⚠️ `jh-dept-picker` 仅用于选择，展示请使用 `jh-text`
+
+---
+
+## 与手动实现对比
+
+### 使用 jh-dept-picker（推荐）
+
+```vue
+<jh-dept-picker v-model="form.deptId" />
+```
+
+### 手动实现（不推荐）
+
+```vue
+<el-tree-select v-model="form.deptId" :data="deptTree" />
+```
+
+❌ 需要自己加载部门树  
+❌ 需要处理父子关系  
+❌ 回显逻辑复杂
+
+---
+
+## 最佳实践
+
+### 1️⃣ 编辑 & 展示分离
+
+| 场景 | 编辑           | 展示    |
+| ---- | -------------- | ------- |
+| 部门 | jh-dept-picker | jh-text |
+
+---
+
+### 2️⃣ 多选返回值说明
+
+```ts
+// 单选
+deptId: "d001";
+
+// 多选
+deptIds: ["d001", "d002"];
+```
+
+---
+
+### 3️⃣ 树形选择说明
+
+- 默认父子关联
+- `checkStrictly=true` 时父子不互相关联
+
+---
+
+## 注意事项
+
+1. **组件内部已处理部门数据加载**
+   - 不需要手动请求接口
+   - 支持树形结构与自动回显
+
+2. **仅返回部门 ID**
+   - 部门名称展示统一使用 `jh-text`
+
+3. **多选字段类型**
+   - 必须使用数组接收
+
+---
+
+## 🎯 真实项目示例
+
+### 示例 1：新增页面
+
+```vue
+<jh-dept-picker v-model="form.deptId" />
+```
+
+### 示例 2：查询条件
+
+```vue
+<jh-dept-picker v-model="query.deptIds" multiple />
+```
+
+---
+
+## 🚀 快速开始
+
+- **单选**：直接使用 v-model
+- **多选**：添加 `multiple`
+- **部门展示**：统一使用 `jh-text type="dept"`
+
+**推荐作为平台统一的部门选择组件使用！**