添加合同签订模块

uniapp/common/dictUtil使用说明.md

@@ -0,0 +1,283 @@
+# 字典工具类使用说明
+
+## 概述
+
+`dictUtil.js` 是一个专门用于批量获取和缓存字典数据的工具类，解决了原有单个接口调用次数过多、用户体验不佳的问题。
+
+## 主要功能
+
+1. **批量获取字典数据** - 一次性获取多个字典，减少接口调用
+2. **智能缓存机制** - 自动缓存数据，避免重复请求
+3. **业务场景支持** - 根据业务场景批量获取相关字典
+4. **兼容性保障** - 保持与原有代码的兼容性
+
+## API 接口
+
+### 后端接口
+
+```php
+// 批量获取字典数据
+GET /api/dict/batch?keys=key1,key2,key3
+
+// 根据业务场景获取字典
+GET /api/dict/scene/{scene}
+
+// 获取单个字典
+GET /api/dict/single/{key}
+
+// 获取字典映射关系
+GET /api/dict/mapping
+
+// 清除字典缓存
+POST /api/dict/clear_cache
+```
+
+## 前端使用方法
+
+### 1. 导入工具类
+
+```javascript
+import dictUtil from '@/common/dictUtil.js'
+```
+
+### 2. 批量获取字典数据
+
+```javascript
+// 方法一：直接批量获取
+const dictKeys = ['SourceChannel', 'source', 'customer_purchasing_power']
+const dictData = await dictUtil.getBatchDict(dictKeys)
+
+// 结果格式：
+// {
+//   'SourceChannel': [
+//     {name: '抖音', value: '1', sort: 0, memo: ''},
+//     {name: '微信', value: '2', sort: 1, memo: ''}
+//   ],
+//   'source': [...],
+//   'customer_purchasing_power': [...]
+// }
+```
+
+### 3. 根据业务场景获取
+
+```javascript
+// 获取客户添加场景的所有字典
+const dictData = await dictUtil.getDictByScene('customer_add')
+
+// 或者使用便捷方法
+const dictData = await dictUtil.getCustomerAddDict()
+```
+
+### 4. 单个字典获取
+
+```javascript
+// 获取单个字典（与原有 util.getDict 兼容）
+const sourceData = await dictUtil.getDict('source')
+```
+
+### 5. 预加载字典数据
+
+```javascript
+onLoad() {
+  // 在页面加载时预加载，提升用户体验
+  const dictKeys = ['SourceChannel', 'source', 'customer_purchasing_power']
+  dictUtil.preloadDict(dictKeys)
+}
+```
+
+### 6. 缓存管理
+
+```javascript
+// 清除指定字典缓存
+dictUtil.clearCache(['SourceChannel', 'source'])
+
+// 清除所有字典缓存
+dictUtil.clearCache()
+```
+
+## 在页面中的完整使用示例
+
+### 原有方式（多次接口调用）
+
+```javascript
+// 原有方式 - 问题：多次接口调用，用户体验差
+async init() {
+  await this.getDict('source_channel')
+  await this.getDict('source')
+  await this.getDict('purchasing_power')
+  await this.getDict('initial_intent')
+  await this.getDict('cognitive_idea')
+  await this.getDict('status')
+  await this.getDict('decision_maker')
+  await this.getDict('distance')
+}
+```
+
+### 优化后的方式（批量获取）
+
+```javascript
+// 优化方式 - 一次接口调用获取所有数据
+import dictUtil from '@/common/dictUtil.js'
+
+export default {
+  onLoad() {
+    // 预加载字典数据
+    this.preloadDictData()
+  },
+  
+  methods: {
+    // 预加载字典数据
+    async preloadDictData() {
+      const dictKeys = [
+        'SourceChannel', 'source', 'customer_purchasing_power', 
+        'preliminarycustomerintention', 'cognitive_concept', 
+        'kh_status', 'decision_maker', 'distance'
+      ]
+      
+      // 静默预加载，不阻塞页面显示
+      dictUtil.preloadDict(dictKeys).catch(error => {
+        console.warn('字典预加载失败:', error)
+      })
+    },
+
+    // 批量获取字典数据
+    async getBatchDictData() {
+      try {
+        uni.showLoading({ title: '加载字典数据...', mask: true })
+
+        const dictKeys = [
+          'SourceChannel',                    // 来源渠道
+          'source',                          // 来源
+          'customer_purchasing_power',       // 购买力
+          'preliminarycustomerintention',    // 客户初步意向度
+          'cognitive_concept',               // 认知理念
+          'kh_status',                      // 客户状态
+          'decision_maker',                 // 决策人
+          'distance'                        // 距离
+        ]
+
+        // 批量获取字典数据
+        const dictData = await dictUtil.getBatchDict(dictKeys)
+        
+        // 处理字典数据
+        this.processDictData(dictData)
+        
+      } catch (error) {
+        console.error('批量获取字典数据失败:', error)
+        // 如果批量获取失败，回退到单个获取
+        await this.fallbackGetDict()
+      } finally {
+        uni.hideLoading()
+      }
+    },
+
+    // 处理批量获取的字典数据
+    processDictData(dictData) {
+      const keyMapping = {
+        'SourceChannel': 'source_channel',
+        'source': 'source',
+        'customer_purchasing_power': 'purchasing_power',
+        'preliminarycustomerintention': 'initial_intent',
+        'cognitive_concept': 'cognitive_idea',
+        'kh_status': 'status',
+        'decision_maker': 'decision_maker',
+        'distance': 'distance'
+      }
+
+      Object.keys(keyMapping).forEach(dictKey => {
+        const localKey = keyMapping[dictKey]
+        const dictItems = dictData[dictKey] || []
+
+        if (Array.isArray(dictItems) && dictItems.length > 0) {
+          const formattedOptions = dictItems.map(item => ({
+            text: item.name || '',
+            value: item.value || ''
+          }))
+          
+          if (this.picker_config[localKey]) {
+            this.picker_config[localKey].options = formattedOptions
+          }
+        }
+      })
+    }
+  }
+}
+```
+
+## 性能优化特性
+
+### 1. 缓存机制
+- 自动缓存字典数据到本地存储
+- 缓存有效期 30 分钟
+- 避免重复请求相同数据
+
+### 2. 批量请求
+- 一次接口调用获取多个字典
+- 减少网络请求次数
+- 提升页面加载速度
+
+### 3. 预加载策略
+- 页面 onLoad 时预加载数据
+- 不阻塞页面显示
+- 用户操作时数据已就绪
+
+### 4. 错误处理
+- 批量获取失败时自动回退到单个获取
+- 缓存获取失败时直接请求接口
+- 保证功能的健壮性
+
+## 兼容性说明
+
+### 向后兼容
+工具类保持与原有 `util.getDict()` 方法的完全兼容：
+
+```javascript
+// 原有代码无需修改，自动使用新的缓存和批量获取机制
+const sourceData = await util.getDict('source')
+
+// 新增的批量获取方法
+const batchData = await util.getBatchDict(['source', 'status'])
+```
+
+### 渐进式升级
+可以逐步将页面迁移到新的批量获取方式：
+
+1. 先导入 `dictUtil`
+2. 在 `onLoad` 中添加预加载
+3. 将 `init` 方法中的多个 `getDict` 调用替换为一次 `getBatchDict` 调用
+
+## 注意事项
+
+1. **字典 Key 映射**：确保后端字典 key 与前端使用的 key 一致
+2. **缓存清理**：如果字典数据有更新，记得清理对应缓存
+3. **错误处理**：在批量获取失败时，有回退机制保证功能正常
+4. **性能限制**：单次最多获取 20 个字典，防止接口性能问题
+
+## 扩展功能
+
+### 自定义业务场景
+
+```javascript
+// 在 DictService.php 中添加新的业务场景
+public function getDictKeysByScene(string $scene): array
+{
+    $sceneMapping = [
+        'customer_add' => ['SourceChannel', 'source', '...'],
+        'personnel_add' => ['gender', 'education', '...'],
+        'your_scene' => ['key1', 'key2', '...'] // 添加自定义场景
+    ];
+
+    return $sceneMapping[$scene] ?? [];
+}
+```
+
+### 添加新的工具方法
+
+```javascript
+// 在 dictUtil.js 中扩展
+dictUtil.getYourSceneDict = async function() {
+    return await this.getDictByScene('your_scene')
+}
+```
+
+通过这种方式，你可以大幅提升字典数据获取的性能和用户体验。