leniu-dev 2.0.0

package/src/skills/websocket-sse/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: websocket-sse
+description: |
+  通用实时通信开发指南。涵盖 WebSocket 双向通信和 SSE 服务端推送的原生 Spring 实现。
+  触发场景：
+  - 实现服务端向客户端推送消息
+  - 实现双向实时通信（聊天、协作）
+  - 管理用户在线状态
+  - 实现系统通知、状态变更实时推送
+  - 多实例部署环境下消息同步
+  触发词：WebSocket、SSE、实时推送、消息通知、在线状态、双向通信、Server-Sent Events、SseEmitter、消息推送
+  注意：如果项目有专属技能，优先使用专属版本。
+---
+
+# 实时通信开发指南（WebSocket & SSE）
+
+> 通用模板。如果项目有专属技能，优先使用。
+
+## 设计原则
+
+1. **选择合适的协议**：单向推送用 SSE，双向通信用 WebSocket。
+2. **认证不可少**：连接建立时必须验证身份（Token / Session）。
+3. **多实例支持**：通过 Redis Pub/Sub 或消息队列同步跨实例消息。
+4. **优雅降级**：客户端应处理断线重连、消息丢失等异常场景。
+
+---
+
+## 方案对比
+
+| 维度 | WebSocket | SSE (Server-Sent Events) |
+|------|-----------|--------------------------|
+| 通信方向 | 双向（全双工） | 单向（服务端 -> 客户端） |
+| 协议 | `ws://` / `wss://` | HTTP（长连接） |
+| 浏览器支持 | 所有现代浏览器 | 所有现代浏览器（IE 除外） |
+| 自动重连 | 需手动实现 | 浏览器原生支持 |
+| 数据格式 | 二进制 / 文本 | 文本（通常 JSON） |
+| 代理兼容 | 可能需特殊配置 | 天然 HTTP 兼容 |
+| 适用场景 | 聊天、协作编辑、游戏 | 通知推送、状态更新、AI 流式响应 |
+
+### 选型决策
+
+```
+需要客户端向服务端发送数据？
+├── 是 → WebSocket
+└── 否 → 需要二进制数据传输？
+        ├── 是 → WebSocket
+        └── 否 → SSE（更简单、更稳定）
+```
+
+---
+
+## 实现模式
+
+### 一、WebSocket（Spring 原生）
+
+#### 1. 配置
+
+```java
+@Configuration
+@EnableWebSocket
+public class WebSocketConfig implements WebSocketConfigurer {
+
+    @Autowired
+    private [你的WebSocket处理器] handler;
+
+    @Autowired
+    private [你的认证拦截器] authInterceptor;
+
+    @Override
+    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
+        registry.addHandler(handler, "/ws")
+            .addInterceptors(authInterceptor)
+            .setAllowedOrigins("https://your-domain.com"); // 生产不用 *
+    }
+}
+```
+
+#### 2. 消息处理器
+
+```java
+@Component
+public class AppWebSocketHandler extends TextWebSocketHandler {
+
+    // 会话管理：userId -> Session
+    private final ConcurrentHashMap<Long, WebSocketSession> sessions = new ConcurrentHashMap<>();
+
+    @Override
+    public void afterConnectionEstablished(WebSocketSession session) {
+        Long userId = getUserId(session);
+        sessions.put(userId, session);
+        log.info("WebSocket 连接建立, userId: {}", userId);
+    }
+
+    @Override
+    protected void handleTextMessage(WebSocketSession session, TextMessage message) {
+        // 处理客户端发来的消息
+        String payload = message.getPayload();
+        log.info("收到消息: {}", payload);
+    }
+
+    @Override
+    public void afterConnectionClosed(WebSocketSession session, CloseStatus status) {
+        Long userId = getUserId(session);
+        sessions.remove(userId);
+        log.info("WebSocket 连接关闭, userId: {}", userId);
+    }
+
+    // 发送消息给指定用户
+    public void sendMessage(Long userId, String message) {
+        WebSocketSession session = sessions.get(userId);
+        if (session != null && session.isOpen()) {
+            try {
+                session.sendMessage(new TextMessage(message));
+            } catch (IOException e) {
+                log.error("发送消息失败, userId: {}", userId, e);
+            }
+        }
+    }
+
+    // 广播给所有在线用户
+    public void broadcast(String message) {
+        sessions.values().forEach(session -> {
+            try {
+                if (session.isOpen()) {
+                    session.sendMessage(new TextMessage(message));
+                }
+            } catch (IOException e) {
+                log.error("广播消息失败", e);
+            }
+        });
+    }
+
+    // 检查用户是否在线
+    public boolean isOnline(Long userId) {
+        WebSocketSession session = sessions.get(userId);
+        return session != null && session.isOpen();
+    }
+}
+```
+
+#### 3. 前端连接
+
+```javascript
+const token = localStorage.getItem('token');
+const ws = new WebSocket(`wss://your-domain.com/ws?token=${token}`);
+
+ws.onopen = () => console.log('连接已建立');
+ws.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+    // 根据 data.type 路由处理
+};
+ws.onclose = () => {
+    // 断线重连
+    setTimeout(() => reconnect(), 3000);
+};
+ws.onerror = (error) => console.error('WebSocket 错误', error);
+```
+
+---
+
+### 二、SSE（Spring 原生）
+
+#### 1. Controller
+
+```java
+@RestController
+@RequestMapping("/sse")
+public class SseController {
+
+    private final ConcurrentHashMap<Long, SseEmitter> emitters = new ConcurrentHashMap<>();
+
+    // 建立 SSE 连接
+    @GetMapping("/connect")
+    public SseEmitter connect(@RequestParam Long userId) {
+        SseEmitter emitter = new SseEmitter(0L); // 0 = 不超时
+
+        emitters.put(userId, emitter);
+
+        emitter.onCompletion(() -> emitters.remove(userId));
+        emitter.onTimeout(() -> emitters.remove(userId));
+        emitter.onError(e -> emitters.remove(userId));
+
+        return emitter;
+    }
+
+    // 关闭连接
+    @GetMapping("/close")
+    public void close(@RequestParam Long userId) {
+        SseEmitter emitter = emitters.remove(userId);
+        if (emitter != null) {
+            emitter.complete();
+        }
+    }
+}
+```
+
+#### 2. 消息推送服务
+
+```java
+@Service
+public class SseMessageService {
+
+    @Autowired
+    private SseController sseController;
+
+    // 推送给指定用户
+    public void sendMessage(Long userId, String message) {
+        SseEmitter emitter = sseController.getEmitter(userId);
+        if (emitter != null) {
+            try {
+                emitter.send(SseEmitter.event()
+                    .name("message")
+                    .data(message));
+            } catch (IOException e) {
+                sseController.removeEmitter(userId);
+                log.error("SSE 推送失败, userId: {}", userId, e);
+            }
+        }
+    }
+
+    // 推送给所有用户
+    public void broadcast(String message) {
+        sseController.getAllEmitters().forEach((userId, emitter) -> {
+            try {
+                emitter.send(SseEmitter.event()
+                    .name("message")
+                    .data(message));
+            } catch (IOException e) {
+                sseController.removeEmitter(userId);
+            }
+        });
+    }
+}
+```
+
+#### 3. 前端连接
+
+```javascript
+const token = localStorage.getItem('token');
+const eventSource = new EventSource(`/sse/connect?userId=${userId}&token=${token}`);
+
+eventSource.addEventListener('message', (event) => {
+    const data = JSON.parse(event.data);
+    // 处理消息
+});
+
+eventSource.onerror = () => {
+    // SSE 原生支持自动重连，通常无需手动处理
+    console.warn('SSE 连接异常');
+};
+
+// 页面卸载时关闭
+window.addEventListener('beforeunload', () => {
+    eventSource.close();
+    navigator.sendBeacon('/sse/close?userId=' + userId);
+});
+```
+
+---
+
+### 三、多实例消息同步
+
+单实例时直接操作内存中的 Session/Emitter 即可。多实例部署时需通过 Redis Pub/Sub 同步：
+
+```java
+@Service
+public class MessageBroadcaster {
+
+    @Autowired
+    private StringRedisTemplate redisTemplate;
+
+    private static final String CHANNEL = "realtime:messages";
+
+    // 发布消息到 Redis
+    public void publish(MessageDTO dto) {
+        redisTemplate.convertAndSend(CHANNEL, JsonUtils.toJson(dto));
+    }
+
+    // 订阅 Redis 消息，投递到本地连接
+    @Bean
+    public RedisMessageListenerContainer listenerContainer(RedisConnectionFactory factory) {
+        var container = new RedisMessageListenerContainer();
+        container.setConnectionFactory(factory);
+        container.addMessageListener((message, pattern) -> {
+            MessageDTO dto = JsonUtils.parse(message.toString(), MessageDTO.class);
+            // 匹配本地在线用户并投递
+            localDelivery(dto);
+        }, new ChannelTopic(CHANNEL));
+        return container;
+    }
+}
+```
+
+**流程**：业务代码调用 publish -> 发布到 Redis Channel -> 所有实例的 Listener 接收 -> 匹配本地在线用户并投递。
+
+---
+
+## 业务集成示例
+
+```java
+@Service
+public class OrderNotifyService {
+
+    @Autowired
+    private SseMessageService sseService;
+
+    public void notifyOrderStatusChange(Order order) {
+        String message = JsonUtils.toJson(Map.of(
+            "type", "ORDER_STATUS_CHANGE",
+            "orderId", order.getId(),
+            "status", order.getStatus(),
+            "updateTime", LocalDateTime.now()
+        ));
+        sseService.sendMessage(order.getBuyerId(), message);
+    }
+}
+```
+
+---
+
+## 常见错误
+
+```java
+// 1. 多实例环境只发本地（消息丢失）
+handler.sendMessage(userId, message);  // 用户可能在其他实例
+// 应使用 Redis Pub/Sub 广播
+
+// 2. 发送纯字符串（前端难解析、不可扩展）
+handler.broadcast("订单已更新");
+// 应使用 JSON + type 字段
+handler.broadcast(JsonUtils.toJson(Map.of("type", "ORDER_UPDATE", "data", orderData)));
+
+// 3. 循环逐个发送（性能差）
+for (Long uid : userIds) {
+    sendMessage(uid, message);
+}
+// 应批量发送或使用广播
+
+// 4. SSE 超时设置不当
+new SseEmitter(30000L);  // 30秒后断开
+// 长连接应设置 0L（不超时）或较大值
+
+// 5. 忘记清理已断开的连接
+// Session/Emitter 断开后仍在 Map 中 -> 内存泄漏
+// 应在 onCompletion/onClose/onError 回调中移除
+
+// 6. WebSocket 未配置认证
+// 连接建立时不校验 Token -> 任何人可连接
+// 应在 HandshakeInterceptor 中校验身份
+```

package/src/skills/workflow-engine/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: workflow-engine
+description: |
+  通用工作流引擎开发指南。涵盖状态机模式、流程引擎选型（Flowable/Camunda/Activiti 对比）、业务集成模式。
+  触发场景：
+  - 设计审批流程（请假、报销、订单审批）
+  - 选择工作流引擎
+  - 实现任务办理（审批、驳回、转办、委派）
+  - 业务模块集成工作流
+  - 监听流程状态变更
+  触发词：工作流、流程、审批、驳回、转办、委派、加签、抄送、流程引擎、Flowable、Camunda、Activiti、状态机、BPMN
+  注意：如果项目有专属技能，优先使用专属版本。
+---
+
+# 工作流引擎开发指南
+
+> 通用模板。如果项目有专属技能，优先使用。
+
+## 设计原则
+
+1. **流程与业务分离**：流程引擎负责流转控制，业务逻辑通过事件监听器/回调接入。
+2. **状态可追溯**：每次流转记录操作人、操作时间、操作意见，形成完整审批链。
+3. **灵活可配**：流程定义应支持可视化设计、动态修改，无需改代码。
+4. **异常可恢复**：流程实例支持挂起、恢复、终止、撤销等操作。
+
+---
+
+## 流程引擎选型对比
+
+| 维度 | Flowable | Camunda | Activiti | 轻量方案（WarmFlow 等） |
+|------|----------|---------|----------|----------------------|
+| 成熟度 | 高 | 高 | 高（社区版停滞） | 中 |
+| 学习曲线 | 中等 | 中等 | 中等 | 低 |
+| BPMN 2.0 | 完整支持 | 完整支持 | 完整支持 | 部分支持 |
+| DMN 决策表 | 支持 | 支持 | 有限 | 不支持 |
+| CMMN 案例 | 支持 | 支持 | 不支持 | 不支持 |
+| 流程设计器 | 内置 Web | 内置 Web + Desktop | 旧版 Eclipse | 简易 Web |
+| 性能 | 优秀 | 优秀 | 良好 | 轻量高效 |
+| Spring Boot | 原生支持 | 原生支持 | 原生支持 | 通常支持 |
+| 商业版 | 有 | 有 | N/A | 通常免费 |
+| 适用场景 | 企业级复杂流程 | 企业级复杂流程 | 已有项目维护 | 简单审批流 |
+
+### 选型决策树
+
+```
+流程复杂度？
+├── 简单审批（3-5步线性流程）
+│   └── 状态机模式 或 轻量流程引擎
+├── 中等（分支、并行、会签）
+│   └── Flowable / Camunda
+└── 复杂（子流程、多实例、DMN、事件）
+    └── Flowable / Camunda
+```
+
+---
+
+## 实现模式
+
+### 模式一：状态机（简单场景）
+
+适用于线性或简单分支的审批流程。
+
+```java
+// 状态枚举
+public enum OrderStatus {
+    DRAFT,      // 草稿
+    PENDING,    // 待审批
+    APPROVED,   // 已通过
+    REJECTED,   // 已驳回
+    CANCELLED;  // 已撤销
+}
+
+// 状态流转规则
+public class OrderStateMachine {
+
+    private static final Map<OrderStatus, Set<OrderStatus>> TRANSITIONS = Map.of(
+        OrderStatus.DRAFT,    Set.of(OrderStatus.PENDING, OrderStatus.CANCELLED),
+        OrderStatus.PENDING,  Set.of(OrderStatus.APPROVED, OrderStatus.REJECTED),
+        OrderStatus.REJECTED, Set.of(OrderStatus.PENDING, OrderStatus.CANCELLED)
+    );
+
+    public void transition(Order order, OrderStatus targetStatus, String operator, String comment) {
+        OrderStatus current = order.getStatus();
+        if (!TRANSITIONS.getOrDefault(current, Set.of()).contains(targetStatus)) {
+            throw new [你的异常类](
+                String.format("不允许从 %s 流转到 %s", current, targetStatus));
+        }
+        order.setStatus(targetStatus);
+        // 记录流转日志
+        saveFlowLog(order.getId(), current, targetStatus, operator, comment);
+    }
+}
+```
+
+### 模式二：流程引擎集成
+
+#### 核心概念
+
+| 概念 | 说明 |
+|------|------|
+| 流程定义（Definition） | 流程模板（BPMN XML），可版本化管理 |
+| 流程实例（Instance） | 基于定义创建的运行时实例 |
+| 任务（Task） | 等待人工处理的节点 |
+| 历史（History） | 已完成的流程/任务记录 |
+| 变量（Variable） | 流程运行时数据，用于条件判断 |
+
+#### 启动流程
+
+```java
+@Service
+public class WorkflowService {
+
+    @Autowired
+    private [你的流程引擎] engine;
+
+    // 启动流程
+    public String startProcess(String processKey, String businessId, Map<String, Object> variables) {
+        variables.put("businessId", businessId);
+        variables.put("initiator", [你的安全工具类].getCurrentUserId());
+
+        // 启动流程实例
+        var instance = engine.startProcessByKey(processKey, businessId, variables);
+        return instance.getId();
+    }
+
+    // 办理任务（审批通过）
+    public void completeTask(String taskId, String comment, Map<String, Object> variables) {
+        // 记录审批意见
+        engine.addComment(taskId, comment);
+        // 完成任务
+        engine.completeTask(taskId, variables);
+    }
+
+    // 驳回
+    public void rejectTask(String taskId, String targetNodeId, String comment) {
+        engine.addComment(taskId, comment);
+        engine.rejectToNode(taskId, targetNodeId);
+    }
+
+    // 转办
+    public void transferTask(String taskId, String targetUserId, String comment) {
+        engine.addComment(taskId, comment);
+        engine.setAssignee(taskId, targetUserId);
+    }
+
+    // 撤销
+    public void cancelProcess(String instanceId, String comment) {
+        engine.deleteProcessInstance(instanceId, comment);
+    }
+}
+```
+
+#### 业务集成 - 事件监听
+
+```java
+@Component
+public class OrderWorkflowListener {
+
+    @Autowired
+    private OrderService orderService;
+
+    // 监听流程状态变更事件
+    @EventListener(condition = "#event.processKey == 'order_approve'")
+    public void onProcessEvent(ProcessStatusEvent event) {
+        String businessId = event.getBusinessId();
+        switch (event.getStatus()) {
+            case "submitted" -> orderService.updateStatus(businessId, "PENDING");
+            case "approved"  -> orderService.updateStatus(businessId, "APPROVED");
+            case "rejected"  -> orderService.updateStatus(businessId, "REJECTED");
+            case "cancelled" -> orderService.updateStatus(businessId, "CANCELLED");
+        }
+    }
+
+    // 监听任务创建事件（发送通知）
+    @EventListener(condition = "#event.processKey == 'order_approve'")
+    public void onTaskCreated(TaskCreatedEvent event) {
+        notificationService.sendNotice(
+            event.getAssignee(),
+            "您有新的审批任务：" + event.getTaskName()
+        );
+    }
+}
+```
+
+#### 办理人类型设计
+
+| 类型 | 标识格式 | 示例 |
+|------|---------|------|
+| 指定用户 | 用户ID | `1001` |
+| 角色 | `role:角色编码` | `role:finance_manager` |
+| 部门 | `dept:部门ID` | `dept:100` |
+| 岗位 | `post:岗位编码` | `post:cfo` |
+| 表达式 | SpEL / UEL | `${order.amount > 10000 ? 'role:director' : 'role:manager'}` |
+
+---
+
+## API 接口设计参考
+
+### 任务相关
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/workflow/start` | POST | 启动流程 |
+| `/workflow/task/complete` | POST | 办理任务（审批通过） |
+| `/workflow/task/reject` | POST | 驳回 |
+| `/workflow/task/transfer` | POST | 转办 |
+| `/workflow/task/delegate` | POST | 委派 |
+| `/workflow/task/todo` | GET | 当前用户待办列表 |
+| `/workflow/task/done` | GET | 当前用户已办列表 |
+| `/workflow/task/copy` | GET | 抄送列表 |
+
+### 实例相关
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/workflow/instance/running` | GET | 运行中实例 |
+| `/workflow/instance/finished` | GET | 已完成实例 |
+| `/workflow/instance/cancel` | PUT | 撤销申请 |
+| `/workflow/instance/history/{businessId}` | GET | 审批记录 |
+
+---
+
+## 常见错误
+
+```java
+// 1. 流程与业务强耦合
+// 在流程引擎的 ServiceTask 中直接操作数据库
+// 应通过事件监听/消息解耦
+
+// 2. 未处理并发审批
+// 多人同时审批同一任务 -> 数据不一致
+// 应在 completeTask 中加锁或使用乐观锁
+
+// 3. 流程变量存放大对象
+variables.put("orderDetail", hugeObject);  // 序列化到数据库，性能差
+// 应只存关键ID，通过 businessId 关联查询
+
+// 4. 忽略流程版本管理
+// 修改流程定义后，已运行的实例可能出错
+// 应使用版本化部署，运行中实例按启动时版本执行
+
+// 5. 审批意见未持久化
+engine.completeTask(taskId, variables);  // 忘记 addComment
+// 应在 complete 前记录审批意见
+
+// 6. 通知不及时
+// 任务创建后没有通知办理人 -> 任务积压
+// 应通过事件监听器自动发送通知
+```