vue2-client 1.18.38 → 1.18.40

package/docs//350/257/267/346/261/202/345/267/245/345/205/267/344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -0,0 +1,353 @@
+# 请求工具使用说明
+
+本文档介绍项目中封装的请求工具及其配置方式。
+
+## 架构概览
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      业务组件                                │
+├─────────────────────────────────────────────────────────────┤
+│           usePost / useRunLogic (响应式 Hook)                │
+├─────────────────────────────────────────────────────────────┤
+│                    restTools.js                             │
+│            (post / get / del / put)                         │
+├─────────────────────────────────────────────────────────────┤
+│                    request.js                               │
+│         (axios 拦截器 + 请求去重 + 错误处理)                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 一、基础请求方法 (restTools.js)
+
+### 1. post - POST 请求
+
+```javascript
+import { post } from '@vue2-client/services/api'
+
+// 基础用法
+const result = await post('/api/user/save', { name: '张三' })
+
+// 带配置
+const result = await post('/api/user/save', { name: '张三' }, {
+  globalLoading: '保存中...',  // 显示全局 Loading
+  dedupe: false                // 关闭请求去重（POST 默认开启）
+})
+```
+
+**配置项说明：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `globalLoading` | `boolean \| string` | `false` | 是否显示全局 Loading，传字符串可自定义提示文字 |
+| `dedupe` | `boolean` | `true` | 请求去重开关，POST 请求默认开启 |
+
+### 2. get - GET 请求
+
+```javascript
+import { get } from '@vue2-client/services/api'
+
+const result = await get('/api/user/list', { page: 1, size: 10 })
+```
+
+### 3. del - DELETE 请求
+
+```javascript
+import { del } from '@vue2-client/services/api'
+
+const result = await del('/api/user/delete', { id: 1 })
+```
+
+### 4. put - PUT 请求
+
+```javascript
+import { put } from '@vue2-client/services/api'
+
+const result = await put('/api/user/update', { id: 1, name: '李四' })
+```
+
+### 5. postByServiceName - 按服务名请求
+
+```javascript
+import { postByServiceName } from '@vue2-client/services/api'
+
+// 自动拼接 URL: /api/{serviceName}/{url}
+const result = await postByServiceName('/user/save', { name: '张三' }, 'af-system')
+
+// 开发环境: /devApi/{serviceName}/{url}
+const result = await postByServiceName('/user/save', { name: '张三' }, 'af-system', true)
+```
+
+---
+
+## 二、Composition API Hooks (usePost.js)
+
+### 1. usePost - 响应式 POST 请求
+
+适用于需要在模板中绑定 loading 状态的场景。
+
+```javascript
+import { usePost } from '@vue2-client/composables'
+
+export default {
+  setup() {
+    const { loading, data, error, execute, reset } = usePost('/api/user/save', {
+      globalLoading: '保存中...',
+      dedupe: true
+    })
+
+    const handleSave = async (formData) => {
+      const { success, data, error } = await execute(formData)
+      if (success) {
+        message.success('保存成功')
+      } else {
+        // 错误处理（可选，拦截器已统一处理）
+        console.error(error)
+      }
+    }
+
+    return { loading, data, error, handleSave }
+  }
+}
+```
+
+**模板使用：**
+
+```html
+<a-button :loading="loading" @click="handleSave(formData)">保存</a-button>
+```
+
+**返回值说明：**
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `loading` | `boolean` | 请求进行中状态（响应式） |
+| `data` | `any` | 请求返回的数据（响应式） |
+| `error` | `Error \| null` | 请求错误信息（响应式） |
+| `execute(params, config)` | `Function` | 执行请求，返回 `{ success, data, error }` |
+| `reset()` | `Function` | 重置状态 |
+
+**execute 返回值：**
+
+```javascript
+const { success, data, error } = await execute(params)
+// success: boolean - 请求是否成功
+// data: any - 成功时的响应数据
+// error: Error | null - 失败时的错误信息
+```
+
+---
+
+## 三、业务逻辑请求 (useRunLogic)
+
+### useRunLogic - 响应式业务逻辑调用
+
+用于调用后端 Logic 业务逻辑，自动拼接 URL。
+
+```javascript
+import { useRunLogic } from '@vue2-client/composables'
+
+export default {
+  setup() {
+    const { loading, data, error, execute, reset } = useRunLogic('getUserInfo', {
+      serviceName: 'af-system',  // 可选，默认使用 VUE_APP_SYSTEM_NAME
+      isDev: false,              // 可选，是否使用开发环境 API
+      globalLoading: '加载中...',
+      dedupe: true
+    })
+
+    const loadUser = async (userId) => {
+      const { success, data: result } = await execute({ userId })
+      if (success) {
+        console.log('用户信息:', result)
+      }
+    }
+
+    return { loading, data, loadUser }
+  }
+}
+```
+
+**URL 拼接规则：**
+- 生产环境: `/api/{serviceName}/logic/{logicName}`
+- 开发环境: `/devApi/{serviceName}/logic/{logicName}`
+
+**配置项说明：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `serviceName` | `string` | `VUE_APP_SYSTEM_NAME` | 服务名称 |
+| `isDev` | `boolean` | `false` | 是否使用开发环境 API |
+| `globalLoading` | `boolean \| string` | `false` | 是否显示全局 Loading |
+| `dedupe` | `boolean` | `false` | 请求去重开关 |
+
+---
+
+## 四、全局功能
+
+### 1. 请求去重
+
+POST 请求默认开启去重，防止用户快速重复点击导致的重复提交。
+
+**工作原理：**
+- 相同的 URL + 参数 组合视为重复请求
+- 重复请求会被直接拒绝（不发起网络请求），控制台输出警告
+- 请求完成后自动清理记录
+
+**关闭去重：**
+
+```javascript
+post('/api/save', data, { dedupe: false })
+```
+
+**错误码：**
+- 重复请求被拦截时，error.code 为 `ERR_DUPLICATE_REQUEST`
+
+### 2. 全局 Loading
+
+显示全屏遮罩 Loading，阻止用户操作。
+
+```javascript
+// 使用默认文字 "加载中..."
+post('/api/save', data, { globalLoading: true })
+
+// 自定义提示文字
+post('/api/save', data, { globalLoading: '正在保存...' })
+```
+
+**特性：**
+- 支持引用计数，多个并发请求时正确处理显示/隐藏
+- 默认 30 秒超时自动隐藏，防止异常情况下 Loading 卡死
+- 可通过 `forceHideGlobalLoading()` 强制隐藏
+
+**手动控制：**
+
+```javascript
+import { 
+  showGlobalLoading, 
+  hideGlobalLoading, 
+  forceHideGlobalLoading 
+} from '@vue2-client/composables/useGlobalLoading'
+
+// 显示 Loading（默认 30 秒超时）
+showGlobalLoading('处理中...')
+
+// 显示 Loading，自定义超时时间（60 秒）
+showGlobalLoading('处理中...', 60000)
+
+// 显示 Loading，禁用超时
+showGlobalLoading('处理中...', 0)
+
+// 隐藏 Loading（引用计数减一）
+hideGlobalLoading()
+
+// 强制隐藏（重置计数器，立即隐藏）
+forceHideGlobalLoading()
+```
+
+---
+
+## 五、EventStream 流式请求
+
+用于 SSE (Server-Sent Events) 场景。
+
+```javascript
+import { startEventStream, startEventStreamPOST } from '@vue2-client/services/api'
+
+// GET 方式
+const stop = startEventStream(
+  '/api/stream/data',
+  { query: 'test' },
+  {},  // headers
+  (data, eventType) => {
+    console.log('收到数据:', data, eventType)
+  },
+  (error) => {
+    console.error('错误:', error)
+  }
+)
+
+// 停止监听
+stop()
+
+// POST 方式
+const stop = startEventStreamPOST('/api/stream/data', params, headers, onData, onError)
+```
+
+---
+
+## 六、最佳实践
+
+### 1. 表单提交场景
+
+```javascript
+const { loading, execute } = usePost('/api/form/save', {
+  globalLoading: '提交中...',
+  dedupe: true  // 防止重复提交
+})
+
+const handleSubmit = async () => {
+  const { success } = await execute(formData)
+  if (success) {
+    message.success('提交成功')
+  }
+  // 错误已由拦截器统一处理，无需额外处理
+}
+```
+
+### 2. 列表查询场景
+
+```javascript
+const { loading, data, execute } = usePost('/api/list/query')
+
+const loadData = async () => {
+  const { success } = await execute({ page: 1, size: 10 })
+  if (success) {
+    tableData.value = data
+  }
+}
+```
+
+### 3. 业务逻辑调用
+
+```javascript
+const { loading, execute } = useRunLogic('calculatePrice', {
+  globalLoading: '计算中...'
+})
+
+const calculate = async () => {
+  const { success, data } = await execute({ productId: 1, quantity: 10 })
+  if (success) {
+    price.value = data.totalPrice
+  }
+}
+```
+
+### 4. 错误处理模式
+
+```javascript
+const { execute } = usePost('/api/save')
+
+// 模式一：只关心成功（推荐，错误由拦截器统一处理）
+const handleSave = async () => {
+  const { success, data } = await execute(formData)
+  if (success) {
+    message.success('保存成功')
+  }
+}
+
+// 模式二：需要自定义错误处理
+const handleSave = async () => {
+  const { success, data, error } = await execute(formData)
+  if (success) {
+    message.success('保存成功')
+  } else if (error?.code === 'ERR_DUPLICATE_REQUEST') {
+    // 重复请求，静默处理
+  } else {
+    // 自定义错误处理
+    message.error('保存失败: ' + error?.message)
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue2-client",
-  "version": "1.18.38",
+  "version": "1.18.40",
   "private": false,
   "scripts": {
     "serve": "SET NODE_OPTIONS=--openssl-legacy-provider && vue-cli-service serve --no-eslint",

package/src/base-client/components/common/XDatePicker/demo.vue

@@ -23,6 +23,12 @@ export default defineComponent({
   components: { XFormDatePicker },
   setup () {
     const formValues = reactive({
+      '时间选择器-新增模式': null,
+      '时间选择器-查询EQUALS': null,
+      '时间选择器-查询BETWEEN': null,
+      '时间范围选择器-新增模式': null,
+      '时间范围选择器-查询BETWEEN': null,
+
       '单日选择器-新增模式': null,
       '单日选择器-查询EQUALS': null,
       '单日选择器-查询BETWEEN': null,
@@ -49,6 +55,31 @@ export default defineComponent({
     }])
 
     const all = reactive([
+      {
+        title: '时间选择器-新增模式',
+        attr: { type: 'timePicker' },
+        mode: '新增'
+      },
+      {
+        title: '时间选择器-查询EQUALS',
+        attr: { type: 'timePicker', queryType: 'EQUALS' },
+        mode: '查询'
+      },
+      {
+        title: '时间选择器-查询BETWEEN',
+        attr: { type: 'timePicker', queryType: 'BETWEEN' },
+        mode: '查询'
+      },
+      {
+        title: '时间范围选择器-新增模式',
+        attr: { type: 'timeRangePicker' },
+        mode: '新增'
+      },
+      {
+        title: '时间范围选择器-查询BETWEEN',
+        attr: { type: 'timeRangePicker', queryType: 'BETWEEN' },
+        mode: '查询'
+      },
       {
         title: '单日选择器-新增模式',
         attr: { type: 'datePicker' },

package/src/base-client/components/common/XDatePicker/index.vue

@@ -94,6 +94,26 @@ export default {
         this.yearShowOne = false
       },
     },
+    // 时间范围选择器的开始时间
+    timeRangeStartValue: {
+      get () {
+        return Array.isArray(this.value) && this.value.length > 0 ? this.value[0] : undefined
+      },
+      set (val) {
+        const end = (Array.isArray(this.value) && this.value.length > 1) ? this.value[1] : ''
+        this.$emit('change', [val || '', end])
+      },
+    },
+    // 时间范围选择器的结束时间
+    timeRangeEndValue: {
+      get () {
+        return Array.isArray(this.value) && this.value.length > 1 ? this.value[1] : undefined
+      },
+      set (val) {
+        const start = (Array.isArray(this.value) && this.value.length > 0) ? this.value[0] : ''
+        this.$emit('change', [start, val || ''])
+      },
+    },
     // 格式化类型
     formatType () {
       let defaultFormat = 'YYYY-MM-DD HH:mm:ss'
@@ -111,6 +131,8 @@ export default {
         defaultFormat = 'YYYY-MM'
       } else if (['yearRangePicker', 'yearPicker'].includes(this.attr.type)) {
         defaultFormat = 'YYYY'
+      } else if (['timePicker', 'timeRangePicker'].includes(this.attr.type)) {
+        defaultFormat = 'HH:mm:ss'
       }
       return (
         (this.mode === '查询' && this.attr.queryValueFormat
@@ -146,6 +168,7 @@ export default {
         rangePicker: ['开始日期', '结束日期'],
         monthRangePicker: ['开始月份', '结束月份'],
         yearRangePicker: ['开始年份', '结束年份'],
+        timeRangePicker: ['开始时间', '结束时间'],
       }
       return placeholders[this.attr.type] || ['开始', '结束']
     },
@@ -256,6 +279,44 @@ export default {
     "
     style="width: 100%"
   />
+  <!-- 时间选择器 -->
+  <a-time-picker
+    v-else-if="attr.type === 'timePicker'"
+    :getCalendarContainer="enablePopupToBody? undefined :getCalendarContainer"
+    :getPopupContainer="enablePopupToBody? getBodyContainer : undefined"
+    v-model="localValue"
+    :disabled="disabled || readOnly"
+    style="width: 100%"
+    placeholder="请选择时间"
+    :format="formatType"
+    :valueFormat="formatType"
+  />
+  <!-- 时间范围选择器 -->
+  <div
+    v-else-if="attr.type === 'timeRangePicker'"
+    style="display: flex; align-items: center; gap: 8px; width: 100%">
+    <a-time-picker
+      :getCalendarContainer="enablePopupToBody? undefined :getCalendarContainer"
+      :getPopupContainer="enablePopupToBody? getBodyContainer : undefined"
+      v-model="timeRangeStartValue"
+      :disabled="disabled || readOnly"
+      style="flex: 1"
+      :placeholder="placeholder[0]"
+      :format="formatType"
+      :valueFormat="formatType"
+    />
+    <span style="color: rgba(0, 0, 0, 0.45)"> - </span>
+    <a-time-picker
+      :getCalendarContainer="enablePopupToBody? undefined :getCalendarContainer"
+      :getPopupContainer="enablePopupToBody? getBodyContainer : undefined"
+      v-model="timeRangeEndValue"
+      :disabled="disabled || readOnly"
+      style="flex: 1"
+      :placeholder="placeholder[1]"
+      :format="formatType"
+      :valueFormat="formatType"
+    />
+  </div>
   <!-- 单日范围选择器 / 月份范围选择器/ 年份范围选择器  -->
   <a-range-picker
     v-else-if="

package/src/base-client/components/common/XForm/XForm.vue

@@ -302,6 +302,8 @@ export default {
         monthRangePicker: 'YYYY-MM',
         datePicker: 'YYYY-MM-DD',
         rangePicker: 'YYYY-MM-DD HH:mm:ss',
+        timePicker: 'HH:mm:ss',
+        timeRangePicker: 'HH:mm:ss',
       }
       let format = formatMap[type]
 
@@ -331,7 +333,7 @@ export default {
         default:
           return undefined
       }
-      if (['monthPicker', 'yearPicker', 'datePicker'].includes(type)) {
+      if (['monthPicker', 'yearPicker', 'datePicker', 'timePicker'].includes(type)) {
         if (queryType === 'BETWEEN') {
           return [start, end]
         }
@@ -340,7 +342,7 @@ export default {
         } else {
           return end
         }
-      } else if (['rangePicker', 'yearRangePicker', 'monthRangePicker'].includes(type)) {
+      } else if (['rangePicker', 'yearRangePicker', 'monthRangePicker', 'timeRangePicker'].includes(type)) {
         return [start, end]
       }
       return [start, end]
@@ -348,7 +350,7 @@ export default {
     setFormProps (formData, item) {
       formData[item.model] = undefined
       if (item.queryFormDefault) {
-        if (['datePicker', 'rangePicker', 'yearPicker', 'monthPicker', 'yearRangePicker', 'monthRangePicker'].includes(item.type)) {
+        if (['datePicker', 'rangePicker', 'yearPicker', 'monthPicker', 'yearRangePicker', 'monthRangePicker', 'timePicker', 'timeRangePicker'].includes(item.type)) {
           formData[item.model] = this.getDateRange(item)
         } else if (['treeSelect', 'select', 'checkbox'].includes(item.type) && ['curOrgId', 'curDepId', 'curUserId'].includes(item.queryFormDefault)) {
           if (item.queryFormDefault === 'curOrgId') {

package/src/base-client/components/common/XForm/XFormItem.vue

@@ -383,7 +383,7 @@
   </x-form-col>
   <!-- 时间 日期 框整合 -->
   <x-form-col
-    v-else-if="['datePicker', 'rangePicker', 'yearPicker', 'monthPicker', 'yearRangePicker', 'monthRangePicker'].includes(attr.type) && show"
+    v-else-if="['datePicker', 'rangePicker', 'yearPicker', 'monthPicker', 'yearRangePicker', 'monthRangePicker', 'timePicker', 'timeRangePicker'].includes(attr.type) && show"
     :labelCol="labelCol"
     :flex="attr.flex">
     <a-form-model-item