@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-session/references/multi-device.md

@@ -0,0 +1,149 @@
+# 多端登录与强制下线（session）
+
+> 同一账号多设备登录策略 / 强制下线 / 单点登出。
+
+---
+
+## 1. 多端登录策略
+
+| 模式 | 行为 | 适用 |
+|------|------|------|
+| **互踢模式** | 新登录踢掉旧设备 | 个人用户系统（默认）|
+| **并行模式** | 多端共存 | 企业内部系统（老板 + 秘书共用） |
+| **限数模式** | 最多 N 个端 | 限定设备数（≤3）|
+
+## 2. 配置
+
+```yaml
+# application.yml
+session:
+  multi-device: kick    # kick / parallel / limited
+  max-devices: 3        # limited 模式时生效
+```
+
+## 3. 互踢模式（默认）
+
+### 3.1 行为
+
+```
+用户 A 在 PC 登录（sessionId: sid_pc）
+   ↓
+用户 A 在手机登录
+   ↓
+平台检测到 multi-device=kick
+   ↓
+自动让 sid_pc 失效
+   ↓
+PC 端下次请求 → 401 → 跳登录页
+```
+
+### 3.2 实现
+
+```java
+@Service
+public class SessionServiceImpl implements ISessionService {
+
+    @Override
+    public LoginResult login(LoginRequest req) {
+        // 1. 校验用户名密码
+        UserDTO user = userService.authenticate(req);
+
+        // 2. 互踢：删除该用户其他 session
+        if ("kick".equals(sessionConfig.getMultiDeviceMode())) {
+            evictOtherSessions(user.getUserId(), req.getDeviceId());
+        }
+
+        // 3. 创建新 session
+        return createSession(user, req);
+    }
+}
+```
+
+## 4. 强制下线（管理员踢人）
+
+### 4.1 场景
+
+管理员发现账号被盗 / 用户离职 / 违规操作 → 立即下线。
+
+### 4.2 接口
+
+```java
+@PostMapping("/admin/session/{sessionId}/kick")
+@PreAuthorize("hasRole('ADMIN')")
+public Result kick(@PathVariable String sessionId) {
+    sessionService.kick(sessionId, "管理员强制下线");
+    return Result.success();
+}
+```
+
+### 4.3 平台通知（可选）
+
+```java
+@EventListener
+public void onSessionKicked(SessionKickedEvent event) {
+    // 通知用户（站内信 / 邮件 / 短信）
+    messageService.send(event.getUserId(), "您的账号在另一地点登录，已被强制下线");
+}
+```
+
+## 5. 单点登出（SSO Logout）
+
+详见 [meritdata-platform-sso 指南](../meritdata-platform-sso/references/guide.md)。
+
+```java
+@PostMapping("/auth/logout")
+public Result logout(HttpServletRequest request) {
+    String token = request.getHeader("Authorization");
+    sessionService.logout(token);
+    // SSO 单点登出：通知所有应用注销
+    ssoClient.logoutAll(token);
+    return Result.success();
+}
+```
+
+## 6. 设备识别
+
+### 6.1 设备 ID
+
+```java
+// 客户端生成（UUID）持久化到 localStorage
+String deviceId = request.getHeader("X-Device-Id");
+
+// 服务端：同一 deviceId 复用 session（不踢自己）
+```
+
+### 6.2 设备指纹
+
+```java
+String fingerprint = DeviceFingerprint.from(request);
+// 包含 userAgent + screen + timezone + 设备 ID
+```
+
+## 7. ❌ 反模式
+
+### 7.1 ❌ 不踢同账号多端
+
+```java
+// ❌ 错：允许多人共用账号 → 责任无法追溯
+public LoginResult login(LoginRequest req) {
+    return createSession(user, req);  // 不踢旧 session
+}
+```
+
+✅ 默认踢旧 session（除同 deviceId）。
+
+### 7.2 ❌ 强制下线后无通知
+
+```java
+// ❌ 错：踢了用户也不知道
+sessionService.kick(sessionId);
+// 用户下次请求才发现 401
+```
+
+✅ 推消息通知用户。
+
+## 8. 关联阅读
+
+- [guide.md](guide.md) — 会话基础
+- [online-monitor.md](online-monitor.md) — 在线监控
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,195 @@
+# 在线用户与会话监控（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

@@ -0,0 +1,41 @@
+---
+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

@@ -0,0 +1,144 @@
+# 国密算法指南（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

@@ -0,0 +1,177 @@
+# 国密密钥管理（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)