初始化

.cursor/skills/message-queue/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: message-queue
+version: 1.0.0
+description: "配置 Hyperf AsyncQueue + Redis 实现后台任务处理。当需要异步任务、消息队列或延迟队列时使用。含重试策略和事件驱动模式。"
+---
+
+# Hyperf Async Queue (Message Queue)
+
+## 触发条件
+
+用户需要异步处理任务：通知发送、数据同步、超时检测、日志记录、批量操作。
+
+## 执行流程
+
+### Phase 0: 加载规范
+
+读取 `.cursor/rules/013-backend.mdc`、`016-swoole.mdc`，提取 Job 命名、DI、协程安全、连接池。
+
+### Phase 1: 队列配置
+
+`config/autoload/async_queue.php`：Redis 驱动、channel、retry_seconds 指数退避、handle_timeout、processes、concurrent。可配置 default 与 notification 等多队列。
+
+### Phase 2: Job 类
+
+继承 `Hyperf\AsyncQueue\Job`，`maxAttempts`、幂等检查、`handle()` 内 try-catch 记录日志后 re-throw 触发重试。
+
+### Phase 3: 投递任务
+
+QueueService 封装 `dispatch`、`dispatchNotification`、`dispatchDelayed`。从 DriverFactory 获取 driver 后 push。
+
+### Phase 4: 使用场景
+
+通知发送、超时检测（延迟 30 分钟）、批量处理（chunk 后逐批 dispatch）。
+
+### Phase 5: 事件驱动
+
+Event → Listener → QueueService.dispatch。Service 更新数据后 event() 触发，Listener 内异步投递多个 Job。
+
+### Phase 6: 监控
+
+队列 health check 命令：Redis 统计 waiting/delayed/failed/timeout，failed > 100 告警。
+
+完整实现见 **Tier 3**。
+
+## 验证
+
+1. [ ] 配置使用环境变量
+2. [ ] Job 幂等
+3. [ ] maxAttempts、retry_seconds 合理
+4. [ ] handle_timeout 大于 Job 最大执行时间
+5. [ ] 关键 Job 有错误日志
+6. [ ] 延迟队列用于超时检测
+7. [ ] 消费进程在 supervisor 注册
+
+## Tier 3 深度参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/queue-implementation.md` | 配置、Job、投递、事件驱动、监控完整代码 |

.cursor/skills/message-queue/references/queue-implementation.md

@@ -0,0 +1,46 @@
+# Message Queue — 实现细节
+
+> 主流程见 SKILL.md，本文档为配置、Job、投递、事件驱动、监控的完整代码。
+
+## 队列配置
+
+```php
+// config/autoload/async_queue.php
+return [
+    'default' => [
+        'driver' => Hyperf\AsyncQueue\Driver\RedisDriver::class,
+        'redis' => ['pool' => 'default'],
+        'channel' => env('QUEUE_CHANNEL', '{queue}'),
+        'timeout' => 2,
+        'retry_seconds' => [1, 5, 10, 30, 60],
+        'handle_timeout' => 60,
+        'processes' => 1,
+        'concurrent' => ['limit' => 10],
+    ],
+    'notification' => [ /* 独立队列，更高优先级 */ ],
+];
+```
+
+## Job 类模板
+
+```php
+class {{JobName}}Job extends Job
+{
+    protected int $maxAttempts = 3;
+    public function __construct(protected readonly int $resourceId, protected readonly array $payload = []) {}
+    public function handle(): void {
+        $resource = $this->getResource();
+        if (!$resource || $this->isAlreadyProcessed($resource)) return;
+        try { $this->process($resource); }
+        catch (\Throwable $e) { logger()->error(...); throw $e; }
+    }
+}
+```
+
+## 投递与事件驱动
+
+QueueService：`dispatch($job, $delay)`、`dispatchNotification($job)`、`dispatchDelayed($job, $delaySeconds)`。事件驱动：Event → Listener → QueueService->dispatch。示例：OrderStatusChanged → 异步通知、同步外部、更新统计缓存（debounce 5s）。
+
+## 监控命令
+
+Redis `{queue}:waiting`、`{queue}:delayed`、`{queue}:failed`、`{queue}:timeout`。failed > 100 告警。