@alanwang-merit/meritdata-platform-skill-package 1.0.10 → 1.0.11

package/skills/meritdata-platform-session/references/online-monitor.md

@@ -1,195 +0,0 @@
-# 在线用户与会话监控（session）
-
-> 在线用户查询 / 活跃会话监控 / 异常会话告警。
-
----
-
-## 1. 在线用户查询
-
-### 1.1 当前用户在线
-
-```java
-@GetMapping("/admin/users/online")
-public PageResult<OnlineUserVO> onlineUsers(OnlineUserQuery query) {
-    return sessionService.listOnlineUsers(query);
-}
-```
-
-返回字段：
-
-```java
-public class OnlineUserVO {
-    private String userId;
-    private String userName;
-    private String sessionId;
-    private String clientIp;
-    private String device;
-    private long loginTime;
-    private long lastAccessTime;
-    private long idleSeconds;       // 空闲秒数
-}
-```
-
-### 1.2 按组织查询
-
-```java
-@GetMapping("/admin/org/{orgId}/online")
-public List<OnlineUserVO> onlineByOrg(@PathVariable String orgId) {
-    return sessionService.listOnlineByOrg(orgId);
-}
-```
-
-## 2. Redis 数据模型
-
-```
-key:    session:{sessionId}
-value:  JSON(SessionInfo)
-TTL:    accessToken 过期时间
-
-key:    user:sessions:{userId}   (Set)
-value:  [sessionId1, sessionId2, ...]
-TTL:    无（管理用）
-
-key:    online:users             (Sorted Set, score=lastAccessTime)
-value:  userId
-```
-
-### 2.1 维护
-
-```java
-// 登录：加入
-redis.opsForSet().add("user:sessions:" + userId, sessionId);
-redis.opsForZSet().add("online:users", userId, lastAccessTime);
-
-// 登出：移除
-redis.opsForSet().remove("user:sessions:" + userId, sessionId);
-redis.opsForZSet().remove("online:users", userId);
-```
-
-## 3. 活跃会话监控
-
-### 3.1 实时活跃
-
-```java
-public long countOnline() {
-    return redis.opsForZSet().zCard("online:users");
-}
-
-// 最近 5 分钟活跃用户
-public Set<String> activeRecently() {
-    long fiveMinAgo = System.currentTimeMillis() - 300_000;
-    return redis.opsForZSet().rangeByScore("online:users", fiveMinAgo, Double.MAX_VALUE);
-}
-```
-
-### 3.2 空闲超时会话
-
-```java
-public List<SessionInfo> findIdleSessions(long idleSeconds) {
-    long threshold = System.currentTimeMillis() - idleSeconds * 1000;
-    Set<String> idleUsers = redis.opsForZSet().rangeByScore("online:users", 0, threshold);
-    // 查每个 userId 的 session 信息
-}
-```
-
-## 4. 异常会话告警
-
-### 4.1 异地登录告警
-
-```java
-@EventListener
-public void onLogin(LoginEvent event) {
-    SessionInfo session = event.getSession();
-    String lastIp = geoLocationService.lastIpOf(session.getUserId());
-
-    if (!lastIp.equals(session.getClientIp())) {
-        // 异地登录
-        alertService.send("USER_LOGIN_ABNORMAL_IP", session);
-    }
-}
-```
-
-### 4.2 短时间多次登录失败
-
-```java
-@EventListener
-public void onLoginFail(LoginFailEvent event) {
-    String userId = event.getUserId();
-    long count = redis.opsForValue().increment("login_fail:" + userId);
-    redis.expire("login_fail:" + userId, 300);  // 5 分钟窗口
-
-    if (count >= 5) {
-        alertService.send("BRUTE_FORCE_SUSPECTED", event);
-        sessionService.lockUser(userId, 300);  // 锁定 5 分钟
-    }
-}
-```
-
-### 4.3 大量会话堆积
-
-```java
-@Scheduled(fixedDelay = 60_000)
-public void checkSessionAnomaly() {
-    for (String userId : sessionService.allActiveUsers()) {
-        int count = sessionService.sessionCount(userId);
-        if (count > 10) {  // 单用户超过 10 个会话
-        alertService.send("ABNORMAL_SESSION_COUNT", Map.of(
-            "userId", userId,
-            "count", count
-        ));
-    }
-}
-```
-
-## 5. 会话统计
-
-### 5.1 峰值并发
-
-```java
-public long peakToday() {
-    // 从监控系统拿（Prometheus / Druid）
-}
-```
-
-### 5.2 平均会话时长
-
-```java
-public Duration averageSessionDuration() {
-    long totalSeconds = 0;
-    int count = 0;
-    for (SessionInfo s : allTodaySessions()) {
-        totalSeconds += (s.getLastAccessTime() - s.getLoginTime()) / 1000;
-        count++;
-    }
-    return Duration.ofSeconds(totalSeconds / count);
-}
-```
-
-## 6. ❌ 反模式
-
-### 6.1 ❌ 在线用户每次实时算
-
-```java
-// ❌ 错：每次请求实时查 Redis 全量
-@GetMapping("/online/count")
-public long count() {
-    Set<String> users = redis.opsForZSet().range("online:users", 0, -1);
-    return users.size();  // 慢！
-}
-```
-
-✅ 用 ZCARD。
-
-### 6.2 ❌ 不清理过期会话
-
-```java
-// ❌ 错：依赖 TTL，但 user:sessions 是 Set 类型，不会因 member 过期自动清
-```
-
-✅ 主动清理或在每次访问时检查。
-
-## 7. 关联阅读
-
-- [guide.md](guide.md) — 会话基础
-- [multi-device.md](multi-device.md) — 多端互踢
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-sm-crypto/SKILL.md

@@ -1,41 +0,0 @@
----
-name: meritdata-platform-sm-crypto
-description: |
-  国密算法（SM2/SM3/SM4）。SM2 非对称加签验签、SM3 摘要、SM4 对称加密；密钥管理；与 RSA/AES 的对比与迁移。
-  触发场景：需要国密合规；与外部国密系统对接；监管要求加密算法国产化。
-  何时不用：纯国际算法（RSA/AES）→ 直接用 JDK；非加密场景 → 用 code-spec。
-metadata:
-  version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
-  risk: high
-  layer: L3
-  sub-layer: L3-C
-  stack: java
-allowed-tools: Read, Grep, Glob, Bash
----
-
-# 国密算法（sm-crypto）
-
-## 触发
-- 需要国密合规（金融/政企/能源行业）
-- 与外部国密系统对接（签名验签、加密通信）
-- 监管要求加密算法国产化
-- 替换现有 RSA/AES 为 SM 系列
-
-## 不触发
-- 纯国际算法（RSA/AES/SHA256）→ 直接 JDK
-- 哈希 / MD5 替代 → 用 code-spec §敏感信息
-- 密钥管理平台 → L4 工具
-
-## 前置约束
-- 密钥**禁止**硬编码在代码（详见 [rules/security-rules.md §三](../../rules/security-rules.md)）
-- 密钥必须从密钥管理服务（KMS）或 Nacos 加密配置读取
-- 国密算法性能低于国际算法，高频场景需评估
-
-## 路由
-- SM2/SM3/SM4 接入 + 用法 → [references/guide.md](references/guide.md)
-- 密钥管理 + KMS 接入 → [references/key-management.md](references/key-management.md)
-- 与 RSA/AES 对比 + 迁移方案 → [references/migration.md](references/migration.md)

package/skills/meritdata-platform-sm-crypto/references/guide.md

@@ -1,144 +0,0 @@
-# 国密算法指南（sm-crypto）
-
-> SM2（非对称）/ SM3（摘要）/ SM4（对称）。国产合规要求场景使用。
-
----
-
-## 1. 算法选型
-
-| 算法 | 类型 | 等价国际算法 | 用途 |
-|------|------|--------------|------|
-| SM2 | 非对称 | RSA / ECDSA | 加签验签、加密（小数据）|
-| SM3 | 摘要 | SHA-256 | 消息摘要、完整性校验 |
-| SM4 | 对称 | AES | 数据加密（大数据）|
-
-**典型组合**：
-- 数据加密：SM4 对称加密 + SM2 加密 SM4 key
-- 签名验签：SM3 摘要 + SM2 签名
-- HTTPS：使用国密 SSL 证书（SM2 密钥交换）
-
-## 2. 引入依赖
-
-```xml
-<dependency>
-    <groupId>org.bouncycastle</groupId>
-    <artifactId>bcprov-jdk15on</artifactId>
-    <version>1.70</version>
-</dependency>
-```
-
-平台提供封装工具类：
-
-```java
-import com.meritdata.cloud.crypto.Sm2Utils;
-import com.meritdata.cloud.crypto.Sm3Utils;
-import com.meritdata.cloud.crypto.Sm4Utils;
-```
-
-## 3. SM2 加签验签
-
-### 3.1 用法
-
-```java
-@Autowired
-private Sm2Utils sm2Utils;
-
-// 加签
-String sign = sm2Utils.sign(plainText, privateKey);
-
-// 验签
-boolean valid = sm2Utils.verify(plainText, sign, publicKey);
-```
-
-### 3.2 密钥格式
-
-- 私钥：HEX 编码的 32 字节
-- 公钥：HEX 编码的 64 字节（未压缩）
-- 平台 KMS 输出的标准格式可直接使用
-
-## 4. SM3 摘要
-
-```java
-@Autowired
-private Sm3Utils sm3Utils;
-
-String hash = sm3Utils.hash(plainText);     // 64 字符 HEX
-
-// HMAC 模式（带密钥）
-String hmac = sm3Utils.hmac(plainText, key);
-```
-
-## 5. SM4 对称加密
-
-### 5.1 CBC 模式（推荐）
-
-```java
-@Autowired
-private Sm4Utils sm4Utils;
-
-// 加密
-String cipher = sm4Utils.encryptCBC(plainText, key, iv);
-
-// 解密
-String plain = sm4Utils.decryptCBC(cipher, key, iv);
-```
-
-### 5.2 ECB 模式（不推荐，相同明文→相同密文）
-
-```java
-// ⚠️ 仅在不关心语义安全的场景使用
-String cipher = sm4Utils.encryptECB(plainText, key);
-```
-
-### 5.3 密钥长度
-
-- 16 字节（128 位）— 标准
-- 32 字节（256 位）— 高安全场景
-
-## 6. 密钥管理
-
-详见 [key-management.md](key-management.md)。
-
-**核心原则**：
-- 密钥**禁止**硬编码在代码
-- 密钥从 KMS（密钥管理服务）或 Nacos 加密配置读取
-- 不同业务使用不同密钥（密钥隔离）
-
-## 7. 与 RSA/AES 迁移
-
-详见 [migration.md](migration.md)。
-
-## 8. ❌ 反模式
-
-### 8.1 ❌ 密钥硬编码
-
-```java
-// ❌ 错
-private static final String SM4_KEY = "0123456789abcdef";
-```
-
-✅ 从 KMS / Nacos 加密配置读取。
-
-### 8.2 ❌ 自实现 SM 算法
-
-```java
-// ❌ 错：自己写 SM 算法（容易出错且未经审计）
-public String mySm2Sign(String data) { ... }
-```
-
-✅ 用平台封装或 Bouncy Castle 标准库。
-
-### 8.3 ❌ 用 SM4 ECB 模式加密敏感数据
-
-```java
-// ❌ 错：相同明文 → 相同密文（语义不安全）
-sm4Utils.encryptECB(plainText, key);
-```
-
-✅ 用 CBC + 随机 IV。
-
-## 9. 关联阅读
-
-- [key-management.md](key-management.md) — 密钥管理
-- [migration.md](migration.md) — 与 RSA/AES 迁移
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-sm-crypto/references/key-management.md

@@ -1,177 +0,0 @@
-# 国密密钥管理（sm-crypto）
-
-> 密钥是密码系统的根。密钥泄露 = 全部数据可解。
-
----
-
-## 1. 密钥管理核心原则
-
-1. **永不硬编码**：代码中不出现密钥明文
-2. **外部存储**：密钥从 KMS 或加密配置读取
-3. **密钥隔离**：不同业务/不同环境用不同密钥
-4. **定期轮换**：建议 90 天轮换一次
-5. **访问审计**：密钥访问有日志
-
-## 2. KMS（密钥管理服务）
-
-### 2.1 平台 KMS 集成
-
-```java
-@Resource
-private IKeyManagementService kmsService;
-
-// 业务系统只拿引用，不拿明文
-String keyAlias = "your-service.sm4.key";
-
-public String getSm4Key() {
-    return kmsService.getKey(keyAlias);
-}
-
-// 加密
-public String encrypt(String plainText) {
-    String key = getSm4Key();
-    return sm4Utils.encryptCBC(plainText, key, generateIV());
-}
-```
-
-### 2.2 平台 KMS 优势
-
-| 特性 | 说明 |
-|------|------|
-| HSM 保护 | 密钥明文不落磁盘，HSM 内存中处理 |
-| 访问审计 | 谁、什么时间、用了哪个密钥 |
-| 自动轮换 | 配置策略自动生成新密钥 |
-| 多租户隔离 | 密钥按业务隔离 |
-
-## 3. 密钥生成
-
-### 3.1 SM2 密钥对
-
-```java
-KeyPair keyPair = Sm2Utils.generateKeyPair();
-String privateKeyHex = Hex.encode(keyPair.getPrivate().getEncoded());
-String publicKeyHex = Hex.encode(keyPair.getPublic().getEncoded());
-```
-
-### 3.2 SM4 对称密钥
-
-```java
-// SM4 密钥 16 字节（128 位）
-byte[] key = new byte[16];
-SecureRandom random = new SecureRandom();
-random.nextBytes(key);
-String keyHex = Hex.encode(key);
-```
-
-**禁止**用 `Random` 或 `Math.random()` 生成密钥。
-
-## 4. 密钥存储
-
-### 4.1 ❌ 禁止的存储方式
-
-```java
-// ❌ 错：硬编码
-private static final String SM4_KEY = "0123456789abcdef";
-
-// ❌ 错：properties 明文
-sm4.key=0123456789abcdef
-
-// ❌ 错：注释中包含密钥
-// 测试密钥：0123456789abcdef
-```
-
-### 4.2 ✅ 推荐的存储方式
-
-| 方式 | 适用 | 说明 |
-|------|------|------|
-| 平台 KMS | 生产环境 | HSM 保护，最安全 |
-| Nacos 加密配置 | 测试环境 | Jasypt / KMS Ref |
-| 环境变量 | 容器化部署 | 配合 Vault |
-| 文件（限权限） | 临时 | chmod 600，限 owner 访问 |
-
-```java
-// ✅ 正确：从环境变量读取
-String key = System.getenv("SM4_KEY");
-
-// ✅ 正确：从 KMS 读取
-String key = kmsService.getKey("your-service.sm4.key");
-```
-
-## 5. 密钥轮换
-
-### 5.1 场景
-
-密钥泄露或定期轮换时，需要切换密钥。
-
-### 5.2 平滑轮换策略
-
-```java
-public class Sm4KeyManager {
-
-    @Resource
-    private IKeyManagementService kmsService;
-
-    private static final String KEY_ALIAS = "your-service.sm4.key";
-
-    /** 加密：用当前主密钥 */
-    public String encrypt(String plain) {
-        String key = kmsService.getCurrentKey(KEY_ALIAS);
-        return sm4Utils.encryptCBC(plain, key, iv());
-    }
-
-    /** 解密：尝试主密钥，失败则尝试历史密钥 */
-    public String decrypt(String cipher) {
-        for (String key : kmsService.getKeyHistory(KEY_ALIAS)) {
-            try {
-                return sm4Utils.decryptCBC(cipher, key, iv());
-            } catch (Exception e) {
-                continue;
-            }
-        }
-        throw new BizException("解密失败");
-    }
-}
-```
-
-### 5.3 轮换步骤
-
-1. 新密钥加入 KMS 密钥历史（同时保留旧密钥）
-2. 业务用新密钥加密新数据
-3. 旧数据用旧密钥解密（兼容）
-4. 等待所有旧数据生命周期结束
-5. 旧密钥从 KMS 删除
-
-## 6. ❌ 反模式
-
-### 6.1 ❌ 密钥和加密数据放一起
-
-```yaml
-# ❌ 错：密钥和数据在同一 Nacos 配置
-your-service.sm4.key: 0123456789abcdef
-your-service.encrypted-data: xxxxx
-```
-
-### 6.2 ❌ 密钥不区分环境
-
-```java
-// ❌ 错：dev 和 prod 用同一密钥
-String key = "0123456789abcdef";
-```
-
-✅ 不同环境用不同密钥。
-
-### 6.3 ❌ 密钥明文记录日志
-
-```java
-// ❌ 错
-log.info("使用密钥加密：{}", key);
-
-// ✅ 正确
-log.info("使用密钥加密：keyAlias={}", keyAlias);  // 只记录别名
-```
-
-## 7. 关联阅读
-
-- [guide.md](guide.md) — 国密算法基础
-- [migration.md](migration.md) — 与 RSA/AES 迁移
-- [SKILL.md](../SKILL.md)