# 字典缓存更新机制

## 概述

本文档说明前后端字典缓存的更新逻辑，确保在字典分类和字典项的增删改等操作后，前端字典缓存能够自动更新。

## 技术实现

### 1. 后端实现

#### 1.1 DictionaryService 更新

在 `app/Services/System/DictionaryService.php` 中添加了 WebSocket 通知功能：

**依赖注入：**
```php
protected $webSocketService;

public function __construct(WebSocketService $webSocketService)
{
    $this->webSocketService = $webSocketService;
}
```

**通知方法：**

1. **字典分类更新通知** (`notifyDictionaryUpdate`)
   - 触发时机：创建、更新、删除、批量删除、批量更新状态
   - 消息类型：`dictionary_update`

2. **字典项更新通知** (`notifyDictionaryItemUpdate`)
   - 触发时机：创建、更新、删除、批量删除、批量更新状态
   - 消息类型：`dictionary_item_update`

**修改的方法列表：**

- `create()` - 创建字典分类后发送通知
- `update()` - 更新字典分类后发送通知
- `delete()` - 删除字典分类后发送通知
- `batchDelete()` - 批量删除字典分类后发送通知
- `batchUpdateStatus()` - 批量更新状态后发送通知
- `createItem()` - 创建字典项后发送通知
- `updateItem()` - 更新字典项后发送通知
- `deleteItem()` - 删除字典项后发送通知
- `batchDeleteItems()` - 批量删除字典项后发送通知
- `batchUpdateItemsStatus()` - 批量更新字典项状态后发送通知

#### 1.2 WebSocket 消息格式

**字典分类更新消息：**
```json
{
  "type": "dictionary_update",
  "data": {
    "action": "create|update|delete|batch_delete|batch_update_status",
    "resource_type": "dictionary",
    "data": {
      // 字典分类数据
    },
    "timestamp": 1234567890
  }
}
```

**字典项更新消息：**
```json
{
  "type": "dictionary_item_update",
  "data": {
    "action": "create|update|delete|batch_delete|batch_update_status",
    "resource_type": "dictionary_item",
    "data": {
      // 字典项数据
    },
    "timestamp": 1234567890
  }
}
```

### 2. 前端实现

#### 2.1 WebSocket Composable

创建了 `resources/admin/src/composables/useWebSocket.js` 来处理 WebSocket 连接和消息监听：

**主要功能：**

1. **初始化 WebSocket 连接**
   - 检查用户登录状态
   - 验证用户信息完整性
   - 建立连接并注册消息处理器

2. **消息处理器**
   - `handleDictionaryUpdate` - 处理字典分类更新
   - `handleDictionaryItemUpdate` - 处理字典项更新

3. **缓存刷新**
   - 接收到更新通知后，自动刷新字典缓存
   - 显示成功提示消息

#### 2.2 App.vue 集成

在 `resources/admin/src/App.vue` 中集成了 WebSocket：

**生命周期钩子：**

```javascript
onMounted(async () => {
  // ... 其他初始化代码
  
  // 初始化 WebSocket 连接
  if (userStore.isLoggedIn()) {
    initWebSocket()
  }
})

onUnmounted(() => {
  // 关闭 WebSocket 连接
  closeWebSocket()
})
```

## 工作流程

### 完整流程图

```
用户操作（增删改字典）
    ↓
后端 Controller 调用 Service
    ↓
Service 执行数据库操作
    ↓
Service 清理后端缓存（Redis）
    ↓
Service 发送 WebSocket 广播通知
    ↓
WebSocket 推送消息到所有在线客户端
    ↓
前端接收 WebSocket 消息
    ↓
触发相应的消息处理器
    ↓
刷新前端字典缓存
    ↓
显示成功提示
```

### 详细步骤

1. **用户操作**
   - 管理员在后台管理界面进行字典分类或字典项的增删改操作
   - 例如：创建新字典分类、修改字典项、批量删除等

2. **后端处理**
   - 接收请求并验证数据
   - 执行数据库操作（INSERT/UPDATE/DELETE）
   - 清理 Redis 缓存（`DictionaryService::clearCache()`）
   - 通过 WebSocket 广播更新通知

3. **WebSocket 通知**
   - 服务端向所有连接的 WebSocket 客户端广播消息
   - 消息包含操作类型、资源类型和更新的数据

4. **前端接收**
   - App.vue 在 onMounted 时初始化 WebSocket 连接
   - 注册消息处理器监听 `dictionary_update` 和 `dictionary_item_update` 事件
   - 接收到消息后调用对应的处理器

5. **缓存刷新**
   - 处理器调用 `dictionaryStore.refresh(true)` 强制刷新缓存
   - 从后端 API 重新加载所有字典数据
   - 更新 Pinia store 中的字典数据
   - 持久化到本地存储

6. **用户反馈**
   - 显示 "字典数据已更新" 的成功提示
   - 页面上的字典数据自动更新，无需手动刷新

## 使用示例

### 示例 1：创建新字典分类

```php
// 后端代码
$dictionary = $dictionaryService->create([
    'name' => '订单状态',
    'code' => 'order_status',
    'description' => '订单状态字典',
    'value_type' => 'string',
    'sort' => 1,
    'status' => true
]);

// 自动触发：
// 1. 清理 Redis 缓存
// 2. 广播 WebSocket 消息
```

前端自动刷新缓存并显示提示。

### 示例 2：更新字典项

```php
// 后端代码
$item = $dictionaryService->updateItem(1, [
    'label' => '已付款',
    'value' => 'paid',
    'sort' => 2
]);

// 自动触发：
// 1. 清理对应字典的 Redis 缓存
// 2. 广播 WebSocket 消息
```

前端自动刷新缓存并显示提示。

### 示例 3：批量操作

```php
// 后端代码
$dictionaryService->batchUpdateStatus([1, 2, 3], false);

// 自动触发：
// 1. 清理所有相关字典的 Redis 缓存
// 2. 广播 WebSocket 消息（包含批量更新的 ID）
```

前端自动刷新缓存并显示提示。

## 注意事项

### 1. WebSocket 连接

- WebSocket 仅在用户登录后建立连接
- 连接失败会自动重试（最多 5 次）
- 页面卸载时会自动关闭连接

### 2. 缓存一致性

- 后端缓存使用 Redis，TTL 为 3600 秒（1 小时）
- 前端缓存使用 Pinia + 本地存储持久化
- WebSocket 通知确保前后端缓存同步更新

### 3. 错误处理

- WebSocket 连接失败不影响页面正常使用
- 缓存刷新失败会在控制台输出错误日志
- 不会阻塞用户操作

### 4. 性能考虑

- 批量操作会一次性清理相关缓存
- WebSocket 广播向所有在线用户推送
- 前端刷新时会重新加载所有字典数据

## 扩展建议

### 1. 细粒度缓存更新

当前实现是全量刷新，未来可以优化为增量更新：

```javascript
// 只更新受影响的字典
async function handleDictionaryUpdate(data) {
  const { action, data: dictData } = data
  
  if (action === 'update' && dictData.code) {
    // 只更新特定的字典
    await dictionaryStore.getDictionary(dictData.code, true)
  } else {
    // 全量刷新
    await dictionaryStore.refresh(true)
  }
}
```

### 2. 权限控制

可以只向有权限的用户发送通知：

```php
// 后端只向有字典管理权限的用户发送
$adminUserIds = User::whereHas('roles', function($query) {
    $query->where('name', 'admin');
})->pluck('id')->toArray();

$this->webSocketService->sendToUsers($adminUserIds, $message);
```

### 3. 消息队列

对于高并发场景，可以使用消息队列异步发送 WebSocket 通知：

```php
// 使用 Laravel 队列
UpdateDictionaryCacheJob::dispatch($action, $data);
```

## 测试建议

### 1. 单元测试

测试后端 WebSocket 通知是否正确发送：

```php
public function testDictionaryUpdateSendsWebSocketNotification()
{
    $this->mockWebSocketService();
    
    $dictionary = DictionaryService::create([
        'name' => 'Test',
        'code' => 'test'
    ]);
    
    // 验证 WebSocket 广播被调用
}
```

### 2. 集成测试

1. 启动后端服务（Laravel-S）
2. 启动前端开发服务器
3. 在浏览器中登录系统
4. 打开开发者工具的 Network -> WS 标签查看 WebSocket 消息
5. 执行字典增删改操作
6. 验证：
   - WebSocket 消息是否正确接收
   - 缓存是否自动刷新
   - 页面数据是否更新
   - 提示消息是否显示

### 3. 并发测试

1. 打开多个浏览器窗口并登录
2. 在一个窗口中进行字典操作
3. 验证所有窗口的缓存是否同步更新

## 故障排查

### 问题 1：前端未收到 WebSocket 消息

**可能原因：**
- WebSocket 服务未启动
- 网络连接问题
- 用户未登录
- Laravel-S 未运行（使用普通 PHP 运行时）

**解决方法：**
1. 检查 Laravel-S 服务是否启动：`php bin/laravels status`
2. 检查浏览器控制台是否有 WebSocket 错误
3. 确认用户已登录且有 token
4. 确认是否在 Laravel-S 环境下运行（WebSocket 通知仅在 Laravel-S 环境下有效）

**注意：**
- WebSocket 通知功能依赖于 Laravel-S (Swoole) 环境
- 在普通 PHP 环境下运行时，WebSocket 通知会优雅降级（不发送通知，但不影响功能）
- 仍需手动刷新页面或使用 API 轮询来获取最新数据

### 问题 2：后端 WebSocket 通知发送失败

**可能原因：**
- Laravel-S 未运行
- Swoole 服务器未启动
- WebSocket 服务实例获取失败

**解决方法：**
1. 确认在 Laravel-S 环境下运行：`php bin/laravels start`
2. 检查 Laravel-S 配置文件 `config/laravels.php`
3. 查看后端日志：`tail -f storage/logs/laravel.log`

**注意：**
- 如果未在 Laravel-S 环境下运行，后端会记录警告日志，但不会报错
- 字典数据仍会正常更新到数据库和 Redis 缓存
- 只是前端不会收到自动更新通知

### 问题 3：缓存未更新

**可能原因：**
- WebSocket 消息处理失败
- API 请求失败
- 前端未连接 WebSocket

**解决方法：**
1. 查看浏览器控制台错误日志
2. 检查网络请求是否成功
3. 手动刷新页面验证 API 是否正常
4. 确认 WebSocket 连接状态（浏览器开发者工具 Network -> WS）

### 问题 3：通知频繁弹出

**可能原因：**
- 批量操作触发了多次通知

**解决方法：**
1. 优化后端批量操作，只发送一次通知
2. 前端添加防抖/节流逻辑

## 总结

通过 WebSocket 实现的字典缓存自动更新机制，确保了前后端数据的一致性，提升了用户体验。用户无需手动刷新页面即可获取最新的字典数据。

### 优势

- ✅ 实时更新，无需手动刷新
- ✅ 多端同步，所有在线用户自动更新
- ✅ 操作透明，用户有明确的反馈
- ✅ 易于扩展，可应用于其他数据类型

### 限制

- 需要稳定的 WebSocket 连接
- 当前实现为全量刷新，可以优化为增量更新
- 依赖后端服务（Laravel-S）正常运行