@agile-team/wl-skills-kit 2.7.0 → 2.7.2

package/files/.github/skills/sync/permission-sync/SKILL.md

@@ -49,6 +49,14 @@ description: "Use when: managing roles, authorizing menus to roles, attaching ac
 
 ---
 
+## ⚠️ 必读公共护栏
+
+本 Skill 遵守 `../_mcp-guardrail.md`（MCP 调用纪律与自愈闭环）。AI 首次执行 sync 类任务时先 `read_file` 加载它。
+
+本 Skill 使用的 MCP 工具：`wls_role_query` / `wls_role_upsert` / `wls_assignable_menus_query` / `wls_role_assign_menus` / `wls_action_query` / `wls_action_upsert`。调用失败时按 guardrail §2 剧本引导用户完善 `env.local.json` 后重试，**不得用 curl/手拼 HTTP 绕开 MCP**。
+
+---
+
 ## MCP 工具调用规范
 
 permission-sync 通过 6 个 MCP 工具完成所有操作（无需手动 fetch）：
@@ -62,7 +70,7 @@ permission-sync 通过 6 个 MCP 工具完成所有操作（无需手动 fetch
 | `wls_action_query`            | 查询页面菜单下的动作（type=A）             |
 | `wls_action_upsert`           | 批量新增动作（按 permission 去重）         |
 
-> 编辑器不支持 MCP 时（如纯命令行使用），可参考 §6 调用接口直连方式手动跑通。
+> 上表 6 个工具覆盖所有场景，**不得以任何理由跳过**。§6 仅为记录 MCP 内部调用的底层接口，供后端/运维联调参考，AI 禁止据此自行发起 HTTP 调用。
 
 ---
 
@@ -207,7 +215,10 @@ permission-sync 通过 6 个 MCP 工具完成所有操作（无需手动 fetch
 
 ---
 
-## 6. 直连接口参考（无 MCP 时的兜底）
+## 6. 后端接口参考（MCP 内部实现，AI 不得调用）
+
+> 本节仅记录 MCP 内部调用的后端路径，用于后端联调 / 运维排查 / kit 维护者参考。
+> **AI 绝不以任何方式直接发起这些请求**。MCP 不可用时的处理方式见末尾「MCP 不可用时怎么办」。
 
 所有接口共用 Headers：
 
@@ -256,3 +267,9 @@ Authorization: Bearer <token>
 - 角色分配可通过重新调用 saveRoleMenus 传旧 menuIds 恢复
 - 新增的角色/动作建议通过后端管理界面手动删除（防止误删生产数据）
 ```
+
+---
+
+## 9. MCP 不可用或调用失败时怎么办
+
+见 `../_mcp-guardrail.md` §2 自愈闭环剧本。**原则**：先帮用户完善 `env.local.json` 里的 token / gatewayPath，重试 MCP 工具。**绝不允许** AI 用 curl/PowerShell/fetch 绕开 MCP 手拼 HTTP。

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

@@ -98,11 +98,11 @@ const query = ref({
 
 ```ts
 // data.ts 查询项配置
-export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
+export const queryItems: BaseQueryItemDesc<any>[] = [
   {
     name: "createDateTime",
-    startName: "createDateTimeStart", // 开始字段
-    endName: "createDateTimeEnd", // 结束字段
+    startName: "createDateTimeStart", // 开始字段（自动拆分）
+    endName: "createDateTimeEnd",     // 结束字段（自动拆分）
     label: "创建日期",
     component: () => {
       return {
@@ -110,18 +110,50 @@ export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
         type: "daterange",
         rangeSeparator: "至",
         showFormat: "YYYY-MM-DD",
-        valueFormat: "YYYY-MM-DD"
+        format: "YYYY-MM-DD"
       };
     }
   }
 ];
 
-// 使用时会自动拆分为 startName 和 endName 两个字段
+// 运行时框架会自动拆分为 startName 和 endName 两个字段：
 // query.createDateTimeStart = "2026-01-01"
 // query.createDateTimeEnd = "2026-01-31"
 ```
 
-### 场景 4：与后端接口参数映射
+### 场景 4：使用 defaultValue 预设值（源码内置）
+
+框架在 `BaseQueryItemDesc` 中内置了丰富的日期范围预设值，配合 `startName` / `endName` 使用：
+
+```ts
+export const queryItems: BaseQueryItemDesc<any>[] = [
+  {
+    name: "dateRange",
+    startName: "startDate",
+    endName: "endDate",
+    label: "业务日期",
+    defaultValue: "recentDay7",  // 默认选中近 7 天
+    component: () => ({ tag: "jh-date", type: "daterange" })
+  },
+];
+```
+
+**全部可用预设值**（源码 `setFormDefaultValue`）：
+
+| 预设值                                | 说明                                     |
+| ------------------------------------- | ---------------------------------------- |
+| `"recentDay3"`                        | 近 3 天（startDate ~ 明天）                |
+| `"recentDay7"`                        | 近 7 天（startDate ~ 明天）                |
+| `"recentDay30"`                       | 近 30 天（startDate ~ 明天）               |
+| `"recentDay3Datetime"`                | 近 3 天（含时分秒 00:00:00 ~ 23:59:59）  |
+| `"rangeDatetimeToday"`                | 今天（00:00:00 ~ 23:59:59）               |
+| `"rangeDayCurrentMonth1ToToday"`      | 本月 1 号 ~ 今天                           |
+| `"rangeDayCurrentMonth1ToLastDay"`    | 本月 1 号 ~ 本月最后一天                   |
+| `"rangeDatetimeCurrentMonth1ToLastDay"` | 本月 1 号 ~ 本月最后一天（含时分秒）       |
+
+> **单字段预设值**（非范围）：`"currentDay"` | `"currentMonth"` | `"currentYear"` | `"currentDept"`
+
+### 场景 5：与后端接口参数映射
 
 ```ts
 // v-model 方式
@@ -183,7 +215,7 @@ params: {
 ### 1️⃣ 统一返回字符串格式（强烈推荐）
 
 ```vue
-<jh-date-range v-model="query.dateRange" value-format="YYYY-MM-DD" />
+<jh-date-range v-model="query.dateRange" format="YYYY-MM-DD" />
 ```
 
 避免 Date / string 混用，接口参数更稳定
@@ -223,7 +255,7 @@ request({
    - 必须使用数组字段接收
    - 推荐默认 `[]`
 
-2. **valueFormat 决定返回类型**
+2. **format 决定返回类型**
    - 默认 `"YYYY-MM-DD"` 字符串数组
    - 不建议返回 Date（容易引入时区/格式问题）
 

package/files/docs/jh-date.md

@@ -53,7 +53,9 @@ const form = ref({
 | clearable            | 是否可清空                   | `boolean`                               | `true`         |
 | teleported           | 是否将下拉面板插入 body      | `boolean`                               | `true`         |
 
-> **提示**: `valueFormat` 为 Element Plus 原生属性,此处统一使用 `format` 属性代替,控制返回值格式。
+> **重要说明**:
+> - `format` 控制 v-model 返回值格式，`showFormat` 控制界面显示格式
+> - 与 Element Plus 的 `value-format` / `format` 命名不同，请使用 jh-date 自己的 `format` 和 `showFormat`
 
 ---
 
@@ -96,36 +98,61 @@ const form = ref({
 
 ### 场景 3：BaseQuery 配置式用法
 
+#### 方式一：使用 logicType 自动映射（推荐）
+
 ```ts
-// data.ts 查询项配置
-export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
+import { BusLogicDataType } from "@jhlc/types/src/logical-data";
+
+export const queryItems: BaseQueryItemDesc<any>[] = [
   {
     name: "deliveryDate",
     label: "交期日期",
-    component: () => {
-      return {
-        tag: "jh-date",
-        type: "date",
-        showFormat: "YYYY-MM-DD",
-        valueFormat: "YYYY-MM-DD" // 或使用 format
-      };
-    }
+    logicType: BusLogicDataType.date,
+    // 自动渲染为 jh-date，默认 type="date"，format="YYYY-MM-DD"
   },
+  {
+    name: "year",
+    label: "年份",
+    logicType: BusLogicDataType.date_yyyy,
+    // 自动渲染为 jh-date，type="year"，format="YYYY"
+  },
+];
+```
+
+> **源码映射规则**（`getFormItemByLogicType`）：
+> - `BusLogicDataType.date` → `DateComponent`（type="date"）
+> - `BusLogicDataType.date_yyyy` → `DateComponent`（type="year", format="YYYY"）
+> - `BusLogicDataType.datetime` → `DateTimeComponent`（format="YYYY-MM-DD HH:mm:ss"）
+> - 自定义 `"month"` → `jh-date`（type="month"）
+
+#### 方式二：使用 component 自定义
+
+```ts
+export const queryItems: BaseQueryItemDesc<any>[] = [
   {
     name: "month",
     label: "月份",
+    logicType: "month" as any,
+    dateFormat: "YYYY-MM",
+    // 源码会渲染为 jh-date，type="month"，format="YYYY-MM"
+  },
+  {
+    name: "deliveryDate",
+    label: "交期日期",
     component: () => {
       return {
         tag: "jh-date",
-        type: "month",
-        showFormat: "YYYY-MM",
-        valueFormat: "YYYY-MM"
+        type: "date",
+        showFormat: "YYYY-MM-DD",
+        format: "YYYY-MM-DD"
       };
     }
-  }
+  },
 ];
 ```
 
+> **dateFormat 可选值**（在 BaseQueryItemDesc 中）：`"YYYY-MM-DD"` | `"YYYY-MM"` | `"YYYYMM"` | `"YYYYMMDD"`
+
 ---
 
 ## 与 el-date-picker 对比
@@ -160,10 +187,10 @@ export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
 
 ### 1️⃣ 统一返回字符串格式
 
-推荐保持 `valueFormat="YYYY-MM-DD"`，避免 Date / string 混用：
+推荐保持 `format="YYYY-MM-DD"`，避免 Date / string 混用：
 
 ```vue
-<jh-date v-model="form.date" value-format="YYYY-MM-DD" />
+<jh-date v-model="form.date" format="YYYY-MM-DD" />
 ```
 
 ---
@@ -185,7 +212,7 @@ export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
 
 ## 注意事项
 
-1. **v-model 返回值取决于 valueFormat**
+1. **v-model 返回值取决于 format**
    - 默认返回 `"YYYY-MM-DD"` 字符串
    - 若不配置可能返回 Date（取决于组件封装）
 

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

@@ -100,6 +100,23 @@ const form = ref({
 
 > ⚠️ `jh-dept-picker` 仅用于选择，展示请使用 `jh-text`
 
+### 场景 4：BaseQuery 配置式用法（推荐）
+
+```ts
+import { BusLogicDataType } from "@jhlc/types/src/logical-data";
+
+export const queryItems: BaseQueryItemDesc<any>[] = [
+  {
+    name: "deptId",
+    label: "部门",
+    logicType: BusLogicDataType.dept,
+    // 自动渲染为 DeptPickerComponent
+  },
+];
+```
+
+> **源码映射**: `BusLogicDataType.dept` → `DeptPickerComponent`
+
 ---
 
 ## 与手动实现对比

package/files/docs/jh-drag-row.md

@@ -176,16 +176,24 @@ onMounted(() => {
 
 ## Props 属性
 
-| 参数       | 说明                                 | 类型      | 默认值  |
-| ---------- | ------------------------------------ | --------- | ------- |
-| top-height | 上部区域的初始高度（单位：px）       | `number`  | -       |
-| topPercent | 上部区域的初始百分比（与 top-height 二选一） | `number`  | -       |
-| bottomHeight | 下部区域的初始高度（单位：px）       | `number`  | -       |
-| bottomPercent | 下部区域的初始百分比       | `number`  | -       |
-| height     | 容器总高度       | `string`  | `"400px"` |
-| sliderWidth | 拖拽分割线的宽度（单位：px） | `number`  | `10`    |
-
-> **提示**: 推荐使用 `top-height` 设置上部区域高度,下部区域会自动填充剩余空间。
+| 参数              | 说明                                         | 类型      | 默认值      |
+| ----------------- | -------------------------------------------- | --------- | ----------- |
+| topHeight         | 上部区域的初始高度（单位：px）               | `number`  | -           |
+| topPercent        | 上部区域的初始百分比（与 topHeight 二选一）   | `number`  | -           |
+| bottomHeight      | 下部区域的初始高度（单位：px）               | `number`  | -           |
+| isNest            | 是否嵌套使用（嵌套在另一个 drag 组件内部）   | `boolean` | `false`     |
+| width             | 容器总宽度                                   | `string`  | `"400px"`   |
+| height            | 容器总高度                                   | `string`  | `"400px"`   |
+| sliderWidth       | 拖拽分割线的高度（单位：px）                 | `number`  | `10`        |
+| sliderColor       | 拖拽手柄指示线颜色                           | `string`  | `"#6f808d"` |
+| sliderBgColor     | 拖拽手柄背景色                               | `string`  | `"#a7caec"` |
+| sliderHoverColor  | 拖拽手柄悬停时指示线颜色                     | `string`  | `"#6f808d"` |
+| sliderBgHoverColor| 拖拽手柄悬停时背景色                         | `string`  | `"#c8dcea"` |
+
+> **提示**:
+> - 推荐使用 `topHeight` 设置上部区域高度，下部区域会自动填充剩余空间
+> - `topPercent` 与 `topHeight` 二选一；当两者都传时，`topHeight` 在 mounted 后会被转换为百分比
+> - 实际项目中通常配合 CSS `height: 100%` 使容器占满可用空间，因此 `width`/`height` prop 仅作为兜底默认值
 
 ## Slots 插槽
 
@@ -506,37 +514,52 @@ const handlePlanChange = (row: any) => {
 
 ## 样式定制
 
-### 修改拖拽手柄样式
+### 通过 Props 自定义手柄颜色（推荐）
+
+```vue
+<jh-drag-row
+  :top-height="380"
+  slider-color="#409eff"
+  slider-bg-color="#e6f0fa"
+  slider-hover-color="#1890ff"
+  slider-bg-hover-color="#bae0ff"
+>
+  ...
+</jh-drag-row>
+```
+
+### 通过 CSS 覆盖手柄样式
 
 ```scss
 :deep(.drager_row) {
   height: 100%;
 
-  // 拖拽手柄
-  .drager {
-    background: #e0e0e0; // 手柄背景色
-    height: 6px; // 手柄高度
-    cursor: row-resize; // 鼠标样式
+  // 拖拽手柄（CSS 类名为 .slider_row）
+  > .slider_row {
+    background: #e0e0e0;
+    cursor: row-resize;
 
     &:hover {
-      background: #1890ff; // 悬停颜色
+      background: #1890ff;
     }
   }
 }
 ```
 
+> **源码 CSS 类名参考**: `.drager_row`（主容器）、`.drager_top`（上部区域）、`.drager_bottom`（下部区域）、`.slider_row`（拖拽手柄）
+
 ### 调整上下区域内边距
 
 ```scss
 :deep(.drager_row) {
   height: 100%;
 
-  .top-area {
-    padding: 10px;
+  .drager_top {
+    padding-bottom: 10px;
   }
 
-  .bottom-area {
-    padding: 10px;
+  .drager_bottom {
+    padding-top: 10px;
   }
 }
 ```

package/files/docs/jh-file-upload.md

@@ -191,6 +191,49 @@ interface FileItem {
 
 ---
 
+## 编程式调用（FormDialog 工具类）
+
+源码中 `FormDialog` 提供了便捷的附件上传/预览方法，无需手动放置 `<jh-file-upload />`：
+
+### uploadAttach — 上传附件弹窗
+
+```ts
+import { FormDialog } from "@jhlc/common-core/src/util/form-dialog";
+
+const handleUpload = async () => {
+  const { type, fileList } = await FormDialog.uploadAttach("上传附件", {
+    relativeType: "order",
+    relativeId: orderId,
+    autoUpload: false,  // 点确认后才上传
+    limit: 5,
+    deletable: true,
+    disabled: false,
+  });
+  if (type === "success") {
+    // 上传成功
+  }
+};
+```
+
+### previewAttach — 预览附件弹窗（只读）
+
+```ts
+FormDialog.previewAttach("查看附件", "order", orderId);
+```
+
+### previewAttachBatch — 批量预览
+
+```ts
+FormDialog.previewAttachBatch("查看全部附件", [
+  { relativeType: "order", relativeId: id1, title: "订单附件" },
+  { relativeType: "contract", relativeId: id2, title: "合同附件" },
+]);
+```
+
+> **源码位置**: `@jhlc/common-core/src/util/form-dialog.ts`
+
+---
+
 ## 🎯 真实项目示例
 
 ### 示例 1：合同附件

package/files/docs/jh-select.md

@@ -50,7 +50,9 @@ const form = ref({
 | collapseTag          | 多选时是否折叠 Tag        | `boolean`                                                | `false`    |
 | teleported           | 是否将下拉面板插入 body   | `boolean`                                                | `true`     |
 
-> **重点**: 当 `dict` 属性存在时,组件会自动加载对应字典数据,无需手动设置 `items`。
+> **重点**:
+> - 当 `dict` 属性存在时，组件会自动加载对应字典数据，无需手动设置 `items`
+> - 源码中 `BusLogicDataType.dict` 和 `BusLogicDataType.company` 都映射为 `SelectComponent`，即公司选择也使用同一组件
 
 ## Events 事件
 
@@ -81,9 +83,38 @@ const form = ref({
 
 ### 场景 4：BaseQuery 配置式用法（推荐）
 
+#### 方式一：使用 logicType 自动映射（推荐）
+
 ```ts
-// data.ts 查询项配置
-export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
+import { BusLogicDataType } from "@jhlc/types/src/logical-data";
+
+export const queryItems: BaseQueryItemDesc<any>[] = [
+  {
+    name: "status",
+    label: "状态",
+    logicType: BusLogicDataType.dict,
+    logicValue: "order_status",
+    // 自动渲染为 jh-select，自动加载字典 order_status 的选项
+  },
+  {
+    name: "companyId",
+    label: "公司",
+    logicType: BusLogicDataType.company,
+    logicValue: "companyId",
+    // BusLogicDataType.company 同样映射为 SelectComponent
+  },
+];
+```
+
+> **源码映射规则**（`getFormItemByLogicType`）：
+> - `BusLogicDataType.dict` → `SelectComponent`
+> - `BusLogicDataType.company` → `SelectComponent`
+> - `BusLogicDataType.enums` → `SelectComponent`
+
+#### 方式二：使用 component 自定义
+
+```ts
+export const queryItems: BaseQueryItemDesc<any>[] = [
   {
     name: "orderStatus",
     label: "操作类型",
@@ -91,7 +122,6 @@ export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
     component: () => {
       return {
         tag: "jh-select",
-        // 方式一：静态数据
         items: [
           { label: "是", value: 1 },
           { label: "否", value: 0 }
@@ -99,16 +129,22 @@ export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
       };
     }
   },
-  {
-    name: "status",
-    label: "状态",
-    logicType: BusLogicDataType.dict,
-    logicValue: "order_status" // 字典 code
-    // 方式二：使用字典数据（会自动加载）
-  }
 ];
 ```
 
+#### historyTop 个人偏好（仅对 jh-select 生效）
+
+```ts
+{
+  name: "customerId",
+  label: "客户",
+  logicType: BusLogicDataType.dict,
+  logicValue: "customer_type",
+  historyTop: true,
+  // 启用后，用户近期选择过的选项会置顶显示
+}
+```
+
 ### 场景 5：静态 items 方式
 
 ```vue
@@ -126,9 +162,10 @@ export const queryItemsConfig: BaseQueryItemDesc<any>[] = [
 
 ## 最佳实践
 
-1. **始终使用 dict 属性**
-   - 不要手动写 options
-   - 保证字典来源统一
+1. **优先使用 logicType + logicValue**
+   - 配置式优于模板式，保证字典来源统一
+   - `logicType: BusLogicDataType.dict` 自动渲染 jh-select
+   - 只有静态选项时才使用 `component` + `items`
 
 2. **配合 jh-text 使用**
    - 列表展示用 `jh-text`

package/files/docs/jh-text.md

@@ -67,9 +67,10 @@ import "@jhlc/common-core";
 | fontSize | 字体大小 | `"extra-small" \| "small" \| "base" \| "medium" \| "large" \| "extra-large"` | - |
 | fontWeight | 字体粗细 | `"light" \| "regular" \| "medium" \| "semi"` | - |
 
-> **提示**: 
-> - `dict` 传入时,会自动设置 `type="dict"`
-> - 同时使用 `logicType` 和 `logicValue` 可以实现自动翻译
+> **源码说明**:
+> - `content` 是框架内部渲染时优先使用的属性（如 `base-form-detail` 自动传入 `content: form[name]`）
+> - `dict` 传入时，会自动设置 `type="dict"`
+> - `logicType` + `logicValue` 是配置式用法的核心，框架会根据类型自动翻译（字典/用户/部门）
 
 ---
 
@@ -132,28 +133,45 @@ import "@jhlc/common-core";
 />
 ```
 
-### 场景 5：BaseDetail 配置式用法
+### 场景 5：BaseFormDetail 配置式用法（自动渲染）
+
+在 `BaseFormDetail` 中，当配置项没有自定义 `component` 时，框架会自动使用 `jh-text` 渲染，并传入 `content`、`logicType`、`logicValue`：
 
 ```ts
-// data.ts 详情项配置
-export const detailItemsConfig: BaseFormDetailDesc[] = [
+import { BusLogicDataType } from "@jhlc/types/src/logical-data";
+
+export const detailItems: BaseFormDetailDesc[] = [
   {
     name: "status",
     label: "状态",
     logicType: BusLogicDataType.dict,
-    logicValue: "order_status"
-    // 会自动渲染为 jh-text 并翻译字典
+    logicValue: "order_status",
+    // 框架自动渲染为: <jh-text :content="form.status" logicType="dict" logicValue="order_status" />
   },
   {
     name: "createUserId",
     label: "创建人",
     logicType: BusLogicDataType.user,
-    logicValue: "userId"
-    // 会自动翻译用户名
-  }
+    // 自动翻译用户 ID 为用户名称
+  },
+  {
+    name: "deptId",
+    label: "部门",
+    logicType: BusLogicDataType.dept,
+    // 自动翻译部门 ID 为部门名称
+  },
+  {
+    name: "remark",
+    label: "备注",
+    // 无 logicType 时直接展示文本
+  },
 ];
 ```
 
+> **源码逻辑**（`form-detail-item.ts` 的 `renderItem`）：
+> 1. 若配置了 `component` → 渲染自定义组件
+> 2. 若未配置 `component` → 自动渲染 `<jh-text :content="form[name]" :logicType :logicValue />`
+
 ---
 
 ## 与手动处理对比