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

package/skills/meritdata-platform-crypto-gm/references/assets/05_/344/272/214/351/200/232/347/224/250/345/267/245/345/205/267-2.1/345/212/240/350/247/243/345/257/206-SM2-SM3-SM4.md

@@ -0,0 +1,176 @@
+---
+name: 二通用工具-2.1加解密-SM2-SM3-SM4
+source-file: 公共资产清单
+source-section: 二、通用工具类 → 2.1 SM2 SM3 SM4 加解密 L687-L835
+keywords: [SM2, SM3, SM4, 国密, Sm2Utils, Sm4Utils, SM3Encoder, encryptWithHMacMD5, 非对称加密, 对称加密, 哈希]
+use-cases: [电子签章, 合同加密, 数据签名, 密码哈希, 敏感数据加密存储]
+related: [15_外部接口-1.16组织人员同步.md, 16_外部接口-1.17资源数据密级.md]
+---
+
+# 2.1 SM2 SM3 SM4 加解密
+
+> **原文章节**：`公共资产清单 → 二、通用工具类 → 2.1 SM2 SM3 SM4 加解密`
+> **行号范围**：L687-L835
+
+## 🎯 一句话
+平台国密套件包含 3 个工具类（Sm2Utils / SM3Encoder / Sm4Utils）共 7 个方法，覆盖非对称加密（SM2）、哈希（SM3）、对称加密（SM4），是电子签章场景的标配。
+
+## 📋 接口/方法清单
+
+### 2.1 SM2 SM3 SM4 加解密
+
+#### Sm2Utils
+
+##### 2.1.1 生成SM2密钥对
+
+完整包路径：`com.meritdata.cloud.utils.Sm2Utils`
+
+方法：`createSM2Key()`
+
+入参：无
+
+返回：MutablePair<String, String> (公钥, 私钥)
+
+使用场景：生成SM2密钥对用于数据加密传输
+
+示例：
+```java
+MutablePair<String, String> keyPair = Sm2Utils.createSM2Key();
+String publicKey = keyPair.getLeft();
+String privateKey = keyPair.getRight();
+```
+
+##### 2.1.2 SM2加密
+
+方法：`encrypt(data, publicKey)`
+
+入参：String data, String publicKey
+
+返回：String
+
+使用场景：SM2公钥加密，用于数据加密传输
+
+示例：
+```java
+String encrypted = Sm2Utils.encrypt(data, publicKey);
+```
+
+##### 2.1.3 SM2解密
+
+方法：`decrypt(data, privateKey)`
+
+入参：String data, String privateKey
+
+返回：String
+
+使用场景：SM2私钥解密，用于解密接收的加密数据，从header获取SM4密钥
+
+示例：
+```java
+// 从请求header获取SM4密钥
+String key = Sm2Utils.decrypt(request.getHeader("smPrivate"), meritdataCloudProperties.getSmPrivateKey());
+```
+
+#### SM3Encoder
+
+##### 2.1.4 SM3加密
+
+完整包路径：`com.meritdata.cloud.utils.SM3Encoder`
+
+方法：`encryptWithHMacMD5(str)` / `encode(str)`
+
+入参：String str
+
+返回：String
+
+使用场景：SM3哈希算法，用于数据完整性校验、密码加密
+
+**注意**：`SM3Encoder`没有`encrypt(str)`方法，应该使用`encryptWithHMacMD5(str)`或从`PasswordEncoder`接口继承的`encode(CharSequence)`方法
+
+示例：
+```java
+// 正确用法 - 使用encryptWithHMacMD5
+String hash = SM3Encoder.encryptWithHMacMD5(originalPassword);
+boolean matches = SM3Encoder.encryptWithHMacMD5(rawPassword).equals(hash);
+
+// 或者实现PasswordEncoder接口的encode方法
+String encoded = SM3Encoder.encode(rawPassword);
+```
+
+##### 2.1.5 SM3加密（带HMAC）
+
+方法：`encryptWithHMacMD5(src)`
+
+入参：String src
+
+返回：String
+
+使用场景：SM3带密钥的哈希运算
+
+示例：
+```java
+String sm3Data = SM3Encoder.encryptWithHMacMD5(word);
+```
+
+#### Sm4Utils
+
+##### 2.1.6 SM4加密（默认密钥）
+
+完整包路径：`com.meritdata.cloud.utils.Sm4Utils`
+
+常量：`SM4_KEY = "nXwqj7JVe@czbD4E"`
+
+方法：`encrypt(text)` / `encrypt(text, key)`
+
+入参：String text, String key(可选)
+
+返回：String
+
+使用场景：SM4对称加密，用于大量数据的加密存储
+
+示例：
+```java
+// 使用默认密钥加密
+String encrypted = Sm4Utils.encrypt(plainText);
+
+// 使用指定密钥加密
+String encrypted = Sm4Utils.encrypt(plainText, privateKey);
+
+// 加密用户数据
+handset = Sm4Utils.encrypt(handset, privateKey);
+email = Sm4Utils.encrypt(email, privateKey);
+```
+
+##### 2.1.7 SM4解密
+
+方法：`decrypt(encryptStr)` / `decrypt(encryptStr, key)` / `decrypt(encryptStr, sm4privateKey, privateKey, flag)`
+
+入参：String encryptStr, String key(可选), String sm4privateKey(可选), String flag(可选)
+
+返回：String
+
+使用场景：SM4对称解密，用于解密存储的加密数据
+
+示例：
+```java
+// 使用默认密钥解密
+String decrypted = Sm4Utils.decrypt(encryptStr);
+
+// 使用指定密钥解密
+String decrypted = Sm4Utils.decrypt(encryptStr, privateKey);
+
+// SM2解密后SM4解密 (flag="1"表示需要SM2解密)
+userNameDec = Sm4Utils.decrypt(username, key, "", "1");
+passwordDec = Sm4Utils.decrypt(password, key, "", "1");
+```
+
+---
+
+## 💡 使用建议
+- **电子签章必须 SM2 + SM4 组合**：合同签署场景使用 SM2 签名 + SM4 加密传输正文，公私钥从 Nacos 配置 `meritdata.cloud.sm4-key` / SM2 公私钥对读取，**禁止硬编码**。
+- **SM3 没有 `encrypt()` 方法**：调用方常误写 `SM3Encoder.encrypt(password)`，正确调用是 `SM3Encoder.encryptWithHMacMD5(password)`。
+- **默认 SM4 密钥已内置**：`Sm4Utils.SM4_KEY = "nXwqj7JVe@czbD4E"`，二开测试可临时使用，生产必须替换为 Nacos 下发的密钥。
+
+## 🔗 相关章节
+- 15_外部接口-1.16组织人员同步.md
+- 16_外部接口-1.17资源数据密级.md

package/skills/meritdata-platform-crypto-gm/references/contract-signing.md

@@ -0,0 +1,60 @@
+# 合同电子签章完整流程
+
+> 来源：基于公司研发攻略 06-系统认证-章节02_token_认证集成 + 平台国密组件（已并入本 skill）
+
+## 签名 + 加密组合（合同场景强制）
+
+### 流程图
+
+```
+发送方：
+  plaintext → SM4 加密 → cipher
+  hash(plaintext) → SM2 签名（私钥）→ sign
+  → 发送 cipher + sign + 公钥
+
+接收方：
+  cipher → SM4 解密 → plaintext
+  SM2 验签（公钥，plaintext，sign）→ 验证完整性
+```
+
+### Java 示例
+
+```java
+@Service
+public class ContractSignService {
+
+    @Autowired
+    private NacosConfigService nacosConfigService;
+
+    public SignedContract signContract(String contractText) {
+        // 1. 从 Nacos 读密钥
+        String sm4Key = nacosConfigService.getConfig("meritdata.cloud.sm4-key");
+        String sm2PrivateKey = nacosConfigService.getConfig("meritdata.cloud.sm2-private-key");
+
+        // 2. SM4 对称加密合同内容
+        String cipher = Sm4Utils.encrypt(sm4Key, contractText);
+
+        // 3. SM3 哈希 + SM2 签名（法律效力）
+        String hash = SM3Encoder.encrypt(contractText);
+        String sign = Sm2Utils.sign(sm2PrivateKey, hash);
+
+        return new SignedContract(cipher, sign, hash);
+    }
+}
+```
+
+## ⚠️ 合规要求
+
+| 要求 | 来源 |
+|------|------|
+| 国密 SM2/SM3/SM4 强制 | 《电子签名法》 |
+| 密钥从 Nacos 配置读 | 美林平台规范 |
+| 签名时间戳 | 防止重放攻击 |
+| 操作审计日志 | ILogPostService 留痕 |
+
+## 密钥轮换
+
+定期（如 90 天）轮换 SM2 密钥对 + SM4 密钥：
+1. Nacos 推送新密钥
+2. 旧合同用旧密钥仍可解密（兼容性保留）
+3. 新合同用新密钥

package/skills/meritdata-platform-crypto-gm/references/crypto.md

@@ -0,0 +1,144 @@
+## 前置条件
+
+Maven 依赖已包含在 `cloud-starter-core` 基础包中，二开项目继承平台脚手架后自动引入，无需额外配置。
+
+| 工具类 | 完整包路径 | 类型 |
+|--------|-----------|------|
+| `Sm2Utils` | `com.meritdata.cloud.utils.Sm2Utils` | 非对称加密（公钥/私钥） |
+| `SM3Encoder` | `com.meritdata.cloud.utils.SM3Encoder` | 哈希摘要 |
+| `Sm4Utils` | `com.meritdata.cloud.utils.Sm4Utils` | 对称加密 |
+
+---
+
+## Sm2Utils — SM2 非对称加密
+
+### 生成密钥对
+
+```java
+MutablePair<String, String> keyPair = Sm2Utils.createSM2Key();
+String publicKey = keyPair.getLeft();   // 公钥
+String privateKey = keyPair.getRight(); // 私钥
+```
+
+### 加密
+
+```java
+String encrypted = Sm2Utils.encrypt(data, publicKey);
+```
+
+### 解密
+
+典型场景：从请求 Header 获取前端传来的 SM4 密钥（经 SM2 加密），用服务端私钥解密。
+
+```java
+String key = Sm2Utils.decrypt(
+    request.getHeader("smPrivate"),
+    meritdataCloudProperties.getSmPrivateKey()
+);
+```
+
+---
+
+## SM3Encoder — SM3 哈希摘要
+
+### 基础用法
+
+用于密码加密存储和比对。
+
+```java
+// 加密
+String hash = SM3Encoder.encryptWithHMacMD5(originalPassword);
+
+// 比对
+boolean matches = SM3Encoder.encryptWithHMacMD5(rawPassword).equals(storedHash);
+```
+
+### PasswordEncoder 接口
+
+`SM3Encoder` 实现了 `PasswordEncoder` 接口：
+
+```java
+String encoded = SM3Encoder.encode(rawPassword);
+```
+
+**注意**：`SM3Encoder` 没有 `encrypt(str)` 方法，应使用 `encryptWithHMacMD5(str)` 或 `encode(CharSequence)`。
+
+---
+
+## Sm4Utils — SM4 对称加密
+
+> **⚠️ 2026-09-10 源码实测**：Sm4Utils 实际有 **5 个 public 静态方法**（3 decrypt + 2 encrypt），不是声明的 2 个。
+
+只使用由已批准配置或密钥服务提供的密钥。不要调用依赖库的默认密钥重载，也不要把密钥、私钥或解密后的值写入代码、文档或日志。
+
+### 方法清单（基于源码实测，2026-09-10）
+
+| # | 方法名 | 返回类型 | 入参 | throws |
+|---|--------|---------|------|--------|
+| 1 | `decrypt` | `String` | `(encryptStr: String)` | - |
+| 2 | `decrypt` | `String` | `(encryptStr: String, sm4privateKey: String)` | - |
+| 3 | `decrypt` | `String` | `(encryptStr: String, sm4privateKey: String, privateKey: String, flag: String)` | `throws Exception` |
+| 4 | `encrypt` | `String` | `(text: String)` | `throws UnsupportedEncodingException` |
+| 5 | `encrypt` | `String` | `(text: String, key: String)` | `throws UnsupportedEncodingException` |
+
+### 类常量
+
+```java
+public static final String SM4_KEY = "nXwqj7JVe@czbD4E"  // 默认密钥
+```
+
+### 典型用法（3 种加密 + 3 种解密场景）
+
+```java
+// 单参数解密（使用类常量 SM4_KEY）
+String plain1 = Sm4Utils.decrypt(encryptedStr);
+
+// 双参数解密（指定 SM4 私钥）
+String plain2 = Sm4Utils.decrypt(encryptedStr, sm4PrivateKey);
+
+// 四参数解密（前后端组合，含 throws Exception）
+String plain3;
+try {
+    plain3 = Sm4Utils.decrypt(encryptedStr, sm4PrivateKey, privateKey, flag);
+} catch (Exception e) {
+    // 错误处理
+}
+
+// 单参数加密（throws UnsupportedEncodingException）
+String encrypted1;
+try {
+    encrypted1 = Sm4Utils.encrypt(text);
+} catch (UnsupportedEncodingException e) {
+    // 错误处理
+}
+
+// 双参数加密（指定密钥）
+String encrypted2;
+try {
+    encrypted2 = Sm4Utils.encrypt(text, key);
+} catch (UnsupportedEncodingException e) {
+    // 错误处理
+}
+```
+
+### ⚠️ 重要陷阱
+
+`encrypt` 方法会抛出受检异常 `UnsupportedEncodingException`，调用方必须 try-catch 或 throws；
+`decrypt` 4 参重载会抛出 `Exception`，包含组合解密失败场景。
+
+### ⚠️ KMS 硬件加密机说明
+
+> ⚠️ **2026-09-10 源码核实警告**：skill 之前提及"**KMS 硬件加密机接入**"——**实测源码中无任何 KMS / HSM 相关实现**。当前国密三件套（Sm2/SM3/SM4）均为**纯软算法**（基于 Hutool + BouncyCastle）。
+> 若需要 KMS/HSM 接入，需自行扩展 `crypto-gm` skill（如新增 KMS Feign Client）。
+
+---
+
+---
+
+## 加解密注意事项
+
+1. `SM3Encoder` 没有 `encrypt()` 方法，使用 `encryptWithHMacMD5()` 或 `encode()`
+2. 不记录、打印或提交密钥和令牌；生产密钥必须可轮换并受访问控制。
+3. 先用现有集成测试验证加密、解密和错误密钥处理，再接入业务接口。
+
+---

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

@@ -0,0 +1,48 @@
+# 密钥管理（Nacos 配置）
+
+> **铁律**：国密密钥**100% 从 Nacos 读取**，**严禁硬编码**到代码或 commit。
+
+## Nacos 配置规范
+
+| 密钥 | 配置项示例 | 长度要求 |
+|------|----------|---------|
+| SM4 key | `meritdata.cloud.sm4-key=0123456789abcdef` | 16 字节（hex 32 字符） |
+| SM2 private key | `meritdata.cloud.sm2-private-key=...` | PEM 格式 |
+| SM2 public key | `meritdata.cloud.sm2-public-key=...` | PEM 格式 |
+
+## Java 读取示例
+
+```java
+@Autowired
+private NacosConfigService nacosConfigService;
+
+String sm4Key = nacosConfigService.getConfig("meritdata.cloud.sm4-key");
+// 立即用，不要缓存在成员变量（多环境隔离）
+String cipher = Sm4Utils.encrypt(sm4Key, data);
+```
+
+## 🚨 反模式（禁止）
+
+```java
+// ❌ 硬编码
+private static final String SM4_KEY = "0123456789abcdef";
+
+// ❌ 从环境变量读（多环境隔离困难）
+String key = System.getenv("SM4_KEY");
+
+// ❌ 从前端传
+@PostMapping("/encrypt")
+public String encrypt(@RequestParam String key, @RequestParam String data) {
+    return Sm4Utils.encrypt(key, data);  // 密钥泄露到前端！
+}
+```
+
+## 密钥轮换
+
+```
+第 0 天   推送 v1 密钥（所有新合同用 v1）
+第 30 天  推送 v2 密钥（新合同用 v2，旧合同仍可解）
+第 60 天  下线 v1 密钥（历史合同已归档）
+```
+
+通过**项目内 Nacos 导出目录**（默认 `nacos_config_export/DEFAULT_GROUP/`）下的 `common-${APP_NAME}.properties` 推送。

package/skills/meritdata-platform-data-secret/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: meritdata-platform-data-secret
+description: MeritData 数据密级。用于密级标签、行级权限、数据脱敏展示。
+metadata:
+  version: "1.0.0"
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-01"
+  risk: high
+  allowed-tools: Read, Grep, Glob
+---
+
+## ⭐ MUST DO
+
+**密级字段在 DB、API、日志、前端全链路显式标注；特权访问必须审计。**
+
+## 触发条件 / 不适用
+
+**适用**：
+- 字段密级标签（公开/内部/秘密/机密）
+- 行级权限过滤
+- 密级降级展示
+
+**不适用**：
+- 通用数据边界 → `.claude/rules/data-boundary-rules.md`
+- 国密算法 → `meritdata-platform-crypto-gm`
+
+## 工作方式
+
+1. 实体继承 `CloudBaseEntity`（自带 `dataSecret` 字段，5 级 10/20/30/40/50）
+2. 方法级启用：`@EnableDataSecretFilter`（**实测 jar 中存在**，非 `@DataSecret`）
+3. API 层：方法标注后 `DataSecretInterceptor` 自动生效
+4. 全工程开关：Nacos `use-platform-secret` / `emp-data-secret` / `resource-data-secret`（任一为 false 跳过）
+5. 前端：根据用户密级脱敏展示
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 漏标密级字段 | 数据泄露 | 全部显式标注 |
+| 特权访问无审计 | 无法追溯 | 强制审计日志 |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 数据边界硬门禁 → `.claude/rules/data-boundary-rules.md`
+  - 国密算法 → `meritdata-platform-crypto-gm`
+- **强制要求**：密级标签必须全链路标注

package/skills/meritdata-platform-data-secret/agents/openai.yaml

@@ -0,0 +1,13 @@
+display_name: "MeritData 数据密级"
+short_description: "密级标签、行级权限、数据脱敏"
+default_prompt: |
+  meritdata-platform-data-secret 处理数据密级场景。
+
+  适用场景：
+  - 字段密级标签
+  - 行级权限过滤
+  - 密级降级展示
+
+  强制约束：
+  - 密级字段全链路标注（DB/API/日志/前端）
+  - 特权访问必须审计

package/skills/meritdata-platform-data-secret/references/assets/10_/344/270/211/345/271/263/345/217/260/346/234/215/345/212/241-3.4/345/244/232/347/263/273/347/273/237/351/233/206/346/210/220+3.5/346/225/260/346/215/256/345/257/206/347/272/247.md

@@ -0,0 +1,91 @@
+---
+name: 多系统集成 + 数据密级过滤
+source-file: 公共资产清单
+source-section: 3.4 多系统集成 + 3.2 外部接口占位 + 3.5 数据密级过滤
+keywords: [WebService, RESTful, 多系统集成, @EnableDataSecretFilter, 数据密级, syncOrg, syncUser, syncResource, syncRole, syncAssign]
+use-cases: [HR系统同步组织人员, 同步资源/角色/权限, 启用数据密级过滤, 行级数据访问控制]
+related: [22, 34, 08]
+---
+
+# 多系统集成 + 数据密级过滤
+
+> **原文章节**：`公共资产清单 → 3.4 多系统集成 + 3.5 数据密级过滤`
+> **行号范围**：L1675–L1735
+
+## 🎯 一句话
+通过 WebService/RESTful 同步组织/人员/资源/角色/权限数据，并通过 `@EnableDataSecretFilter` 注解实现 Hibernate 行级数据密级过滤。
+
+> **原文件 3.2 章节说明**：原文件 L1305–L1310 的 3.2 章节为占位（"参考外部接口清单"），无实质内容。本文件合并该占位说明，所有外部接口详细定义请参考 `微服务外部接口清单-20260716.md`。
+
+## 📋 接口/方法清单
+
+### 3.4 多系统集成
+
+**详细参考**：应用开发平台-基础平台-使用攻略（三）：组织和人员同步.md
+
+基于 WebService 和 RESTful API 的组织、人员、资源、角色、权限同步功能，支持外部系统数据接入。
+
+#### 3.4.1 WebService同步接口
+
+WebService 地址格式：`http://网关地址/应用名称/ws/{服务名}?wsdl`
+
+| 服务名 | 方法名 | 参数 | 返回值 | 说明 | 使用场景 |
+|--------|--------|------|--------|------|----------|
+| syncOrgWebService | syncOrg | xml字符串 | "1"成功/"0"失败 | 组织同步 | 外部HR系统同步组织架构到平台 |
+| syncUserWebService | syncUser | xml字符串 | "1"成功/"0"失败 | 人员同步 | 外部系统同步人员信息（入职、离职、调动） |
+| syncResourceWebService | syncResource | xml字符串 | "1"成功/"0"失败 | 资源同步 | 同步菜单、资源、按钮等权限数据 |
+| syncRoleWebService | syncRole | xml字符串 | "1"成功/"0"失败 | 角色同步 | 同步角色数据到平台 |
+| syncAssignWebService | syncAssign | xml字符串 | "1"成功/"0"失败 | 权限同步 | 同步人员-角色、资源-角色分配关系 |
+
+**完整包路径**：`com.meritdata.cloud.system.manager.ou.sync.ws.impl`
+
+#### 3.4.2 RESTful API同步接口
+
+完整包路径：`com.meritdata.cloud.system.manager.ou.sync.controller.WebApiSyncController`
+
+基础路径：`/webapi/ou/sync`
+
+| 接口路径 | 方法 | 参数 | 说明 | 使用场景 |
+|----------|------|------|------|----------|
+| /webapi/ou/sync/org | POST | orgInfo (xml字符串) | 组织同步 | 外部系统通过REST API同步组织数据 |
+| /webapi/ou/sync/user | POST | userInfo (xml字符串) | 人员同步 | 外部系统通过REST API同步人员数据 |
+| /webapi/ou/sync/resource | POST | resourceInfo (xml字符串) | 资源同步 | 外部系统同步菜单资源数据 |
+| /webapi/ou/sync/role | POST | roleInfo (xml字符串) | 角色同步 | 外部系统同步角色数据 |
+| /webapi/ou/sync/duty | POST | dutyInfo (xml字符串) | 职务同步 | 外部系统同步职务数据 |
+| /webapi/ou/sync/assign | POST | assignInfo (xml字符串) | 权限同步 | 外部系统同步权限分配数据 |
+
+**注意**：调用RESTful API需要在请求Header中携带app-key和app-token进行认证。
+
+---
+
+### 3.5 数据密级过滤
+
+数据密级过滤是基于 Hibernate `@Filter` 实现的行级数据访问控制机制，通过在实体类上标注 `@EnableDataSecretFilter` 注解，自动拦截并过滤用户可访问的数据范围。
+
+#### EnableDataSecretFilter 注解
+
+**使用说明**：
+
+在进行数据密级过滤的实体类或方法上添加 `@EnableDataSecretFilter` 注解，`DataSecretInterceptor` 拦截器会自动启用 Hibernate 的 `secretDataFilter`，根据当前用户的密级过滤高于当前用户密级的数据，只能看低于或等于其密级的数据。
+
+**使用示例**：
+
+```java
+// 标注在方法上
+@LogOperation(type = "select")
+@EnableDataSecretFilter
+public List<Emp> selectEmpList() {
+    return empRepository.findAll();
+}
+```
+
+## 💡 使用建议
+
+1. **组合同步**：WebService 适合内网传统系统集成，RESTful API 适合现代微服务调用，优先选择 RESTful 风格。
+2. **app-key/app-token**：RESTful 调用必须从平台申请并放置在 Header，注意 HTTPS 保护和 Token 定期刷新。
+3. **数据密级必读**：在涉密业务（如合同、人员档案）的查询方法上加 `@EnableDataSecretFilter`，否则密级较高的数据可能被越权查询。
+
+## 🔗 相关章节
+
+- `08_三平台服务-3.3会话信息-SessionUtils.md`（当前用户密级获取）
+- `11_三平台服务-3.6服务通知-CloudFeignMessageClient.md`（同步完成后通过 Feign 通知）

package/skills/meritdata-platform-data-secret/references/data-secret.md

@@ -0,0 +1,89 @@
+## 前置条件
+
+> ⚠️ 本规范已修订（2026-09-10 第二轮）：
+> - 唯一方法级注解：`@EnableDataSecretFilter` / `@EnableSecretFilter`（**均标在方法上**，不是启动类）
+> - ~~`@DataSecret`~~ 注解**不存在**于 cloud-module-base 的 base/tenancy/ 包下，已删除
+> - 全工程开关：Nacos `use-platform-secret` / `emp-data-secret` / `resource-data-secret`（任一为 false 时 DataSecretInterceptor 跳过）
+> - 实测 DataSecretInterceptor 是请求级 Servlet Filter
+> - 字段名 DATA_SECRET（不是 SECRET_LEVEL），类型 BIGINT（不是 INT），值 10/20/30/40/50（不是 1/2/3/4/5）
+> - 详见 references/secret-level-spec.md
+
+
+Maven 依赖已包含在 `cloud-starter-core` 基础包中，二开项目继承平台脚手架后自动引入，无需额外配置。
+
+## 原理
+
+基于 Hibernate `@Filter` 实现。只有目标项目已注册相应拦截器、当前会话带有密级信息且查询路径启用了过滤时，`@EnableDataSecretFilter` 才能生效。
+
+**过滤规则**: 用户只能看到**低于或等于**其自身密级的数据，高于用户密级的数据被自动拦截。
+
+---
+
+## 使用方式
+
+### 方法级 `@EnableDataSecretFilter` 标注（实测 DataSecretInterceptor 是请求级 Servlet Filter）
+
+在需要过滤的查询方法上添加 `@EnableDataSecretFilter`：**标在方法上，不是启动类**：
+
+```java
+@LogOperation(type = "select")
+@EnableDataSecretFilter
+public List<Emp> selectEmpList() {
+    return empRepository.findAll();
+}
+```
+
+### 使用前验证
+
+先查看目标项目中 `@EnableDataSecretFilter` 的已有用法，确认该版本支持的方法或类型目标。不要仅根据实体上的 `@FilterDef` 假定运行时过滤已启用。
+
+---
+
+## 完整包路径（基于 2026-09-10 源码实测）
+
+| 类/注解 | 完整路径 | 所在模块 |
+|---------|------|---------|
+| `@EnableDataSecretFilter` | `com.meritdata.cloud.base.tenancy.EnableDataSecretFilter` | `cloud-module-base`（注解）|
+| `@EnableSecretFilter` | `com.meritdata.cloud.base.tenancy.EnableSecretFilter` | `cloud-module-base`（注解）|
+| `DataSecretInterceptor` | `com.meritdata.cloud.secret.interceptor.DataSecretInterceptor` | **`cloud-starter-core`**（⚠️ 不在 cloud-module-base）|
+| `SecretInfoDTO` | `com.meritdata.cloud.base.dto.SecretInfoDTO` | `cloud-module-base` |
+| `SecretConstEnum` | `com.meritdata.cloud.system.manager.basic.secret.util.SecretConstEnum` | `cloud-system-manage-module` |
+
+> ⚠️ **模块归属说明**：`DataSecretInterceptor` 实际位于 `cloud-starter-core` 模块（不是 `cloud-module-base`），包路径前缀是 `com.meritdata.cloud.secret.interceptor`（不是 `com.meritdata.cloud.base.tenancy`）。
+> 但 `@EnableDataSecretFilter` 注解仍在 `cloud-module-base` 模块的 `base.tenancy` 包下——两者在不同模块。
+
+---
+
+## 密级过滤注意事项
+
+1. 数据密级过滤只在查询时生效，**不阻止手动写入高密级数据**
+2. 依赖当前用户会话中的密级信息，确保 SessionUtils 正常工作
+3. 不得通过省略注解作为通用绕过方式；特权查看必须走已授权、可审计的独立路径。
+4. 至少验证一个允许访问和一个拒绝访问的密级用例。
+
+## ⚠️ 不存在的 SessionUtils 方法（AI 防错警示，2026-09-12 更新）
+
+> **核实警告**：以下方法名**在 `com.meritdata.cloud.utils.SessionUtils` 源码中不存在**——AI 或二开工程师可能编造这些方法名：
+> - ❌ `getUserDataSecret()`（**不存在**）
+> - ❌ `getUserSecret()`（**不存在**）
+> - ❌ `getDataSecret()`（**不存在**）
+> - ❌ `getCurrentDataSecret()`（**不存在**）
+> - ❌ `getSecretLevel()`（**不存在**）
+>
+> SessionUtils 实际 28 个 public 方法（与 `meritdata-platform-session` 技能描述一致）：
+>
+> | 类别 | 方法 |
+> |------|------|
+> | 用户相关 | `getUserId` / `getUserName` / `getEmpId` / `getEmp` / `getEmpName` / `getEmpCode` / `getCurrentUserName` / `getPrincipal` |
+> | 部门/组织 | `getDeptId` / `getDeptCode` / `getDept` / `getDeptName` / `getOrgId` / `getOrg` / `getOrgName` / `getOrgDlevelCode` / `getRootOrgId` / `getRootOrg` / `getAllDepts` / `getAllOrgs` |
+> | 角色/权限 | `getSysRoleCodes` / `getRoleCodes` / `getRoleNames` / `getRoleIds` / `getAuthoritiesIds` / `getWorkGroupIds` |
+> | 会话 | `getTenantId` / `getCurrentLoginIp` |
+>
+> **数据密级实际接口**：
+> 1. **HTTP 跨 JVM**：调用 `cloud-system-manage` 服务的 `POST /certificate/get-secret-relation`
+> 2. **同 JVM 内部**：`@Autowired CertificateController` → `getSecretRelation(request)` 返回 `SecretInfoDTO`（**完整 9 字段**）
+> 3. **数据访问层**：`sessionUtils.getEmp().getGrade()` + `QEmpData` / `QResourceData`
+>
+> **详见 `references/secret-level-spec.md`**（含 SecretInfoDTO 完整 9 字段 + 7 个密级接口 + 3 种获取方式 + 集成示例）
+
+---