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

package/skills/meritdata-dev-docs-file-finder/references/dev-docs/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-dev-docs-file-finder/references/dev-docs/06_/344/270/211/345/271/263/345/217/260/346/234/215/345/212/241-3.1/346/227/245/345/277/227/346/234/215/345/212/241-ILogPostService.md

@@ -0,0 +1,323 @@
+---
+name: 三平台服务-3.1日志服务-ILogPostService
+source-file: 公共资产清单
+source-section: 三、平台服务支撑 → 3.1 日志服务 → ILogPostService L844-L1127
+keywords: [日志服务, ILogPostService, 操作日志, Message, CompareUtils, postLog, postDiyLog, CompareUtils.getCompareLog]
+use-cases: [记录操作日志, 审计日志, 自定义类型日志, 实体变更对比日志]
+related: [07_三平台服务-3.1日志注解-LogDesc-LogOperation.md]
+---
+
+> **OCR 异常提示**：本文件保留了原文 L1125–L1127 的 `# 人员维护` 代码注释原文（原文件混入 OCR 异常），并在上一行配置示例块紧接其后出现，按原貌保留便于追溯。
+
+> **3.2 节空占位提示**：原文件 3.2 节为 6 行空占位（L1305 之后），无实际业务内容；根据拆分规则，3.2 节并入本文件顶部说明（如下 3.2 节占位说明）。
+
+> **3.2 节占位说明**：原文件中 3.2 节位置仅留空占位（无章节标题、无内容），属于 OCR/排版残留；本拆分不补写内容，按原貌标注。
+
+# 3.1 日志服务 — ILogPostService
+
+> **原文章节**：`公共资产清单 → 三、平台服务支撑 → 3.1 日志服务 → ILogPostService`
+> **行号范围**：L844-L1127
+
+## 🎯 一句话
+`ILogPostService` 是平台统一日志服务，封装"操作日志 / 自定义日志"两大写入接口（`POST /post` 和 `POST /post-diy`），通过 `@LogDesc` + `CompareUtils` 自动生成实体变更日志。
+
+## 📋 接口/方法清单
+
+### 3.1 日志服务
+
+基于 `ILogPostService` 的日志服务，所有对外接口均通过 Feign 远程调用实现。支持操作日志、访问日志、登录日志、错误日志等多种日志类型。
+
+**二开服务使用方式**：通过 `@Autowired` 注入 `ILogPostService`，直接调用其方法。
+
+#### ILogPostService
+
+完整包路径：`com.meritdata.cloud.log.service.ILogPostService`
+
+服务名称：`cloud-system-manage`
+
+基础路径：`/api/basic/log`
+
+##### 3.1.1 记录操作日志
+
+方法：`POST /post`
+
+入参：Message param
+
+返回：boolean
+
+使用场景：记录系统操作日志，支持新增、编辑、删除等操作类型的日志记录
+
+**使用步骤：**
+
+日志示例: [用户1:user1] 新增人员[测试用户1:testUser1]
+
+				[用户1:user1] 编辑人员[测试用户1:testUser1]:"姓名"由[测试用户1]变更为[测试用户2],"身份证号码"变更,"邮件地址"变更,"手机号"变更
+
+				[[用户1:user1] 删除人员[测试用户1:testUser1]
+
+1. **注入日志服务**
+
+   ```java
+   // 注入日志服务
+   @Autowired
+   private ILogPostService logPostService;
+   ```
+   
+2. **实体类添加日志注解**@LogDesc(value = "实体类描述", keyField = "name")标注实体描述和新增/编辑/删除等操作日志需要记录的主键字段
+
+3. 对实体类中需要记录到日志中的**字段添加操作日志注解@LogDesc**("字段的中文描述") ，当字段发生变化时会记录变化日志，当添加changeFlag=true时打印"xxx"变更，用于一些敏感信息日志不打印细节仅打印变更操作，多个字段变更操作逗号分隔。
+
+   ```java
+   // 此处为类上的注解，value为实体类的中文描述，如新增人员/编辑人员/删除人员，keyField为日志需要记录的字段：新增人员[用户1]
+   @LogDesc(value = "人员", keyField = "name")
+   @Entity
+   @Table(name = "[PF_ORG_USER]")
+   public class Emp extends CloudBaseEntity implements Serializable {
+   
+       @Id
+       @Column(name = "[ID]", length = 32)
+       private String id;
+   
+       // "姓名"由[修改前值]变更为[修改后值]
+       @Column(name = "[NAME]", length = 200)
+       @LogDesc("姓名")        // 字段描述
+       @DelDesc               // 删除时记录此字段
+       @AddDesc               // 新增时记录此字段
+       private String name;
+   
+       // "编码"由[修改前值]变更为[修改后值]
+       @Column(name = "[CODE]")
+       @LogDesc("编码")
+       private String code;
+       
+   	// "性别"由[空]变更为[女]
+       @Column(name = "[SEX]")
+       @LogDesc(value = "性别", lookupType = "sex")  // lookupType自动转换数据字典
+       private Integer sex;
+   
+       // changeFlag=true打印："手机号"变更
+       @Column(name = "[HANDSET]", length = 256)
+       @LogDesc(value = "手机号", changeFlag = true)  
+       private String handset;
+       
+   	// changeFlag=true打印："身份证号码"变更
+       @Column(name = "[CARD]", length = 60)
+       @LogDesc(value = "身份证号码", changeFlag = true)
+       private String card;
+   }
+   ```
+
+   与消息构造时进行消息比对搭配使用：
+
+   ```java
+   Emp empDb = service.getEmpById(emp.getId());
+   // 自动生成变更日志： "字段描述1"由[修改前值]变更为[修改后值],"字段描述2"由[修改前值]变更为[修改后值]
+   String compareLog = CompareUtils.getCompareLog(empDb, emp);  
+   ```
+
+4. **配置日志模板文件**
+
+   在 `src/main/resources/logs/` 目录下创建 `{module}.logs.properties` 文件：
+
+   必须配置业务模块： {module}.xxx.bmodule；功能模块{module}.xxx.fmodule;
+
+   在日志管理页面展示按业务模块、功能模块进行记录，可进行筛选
+
+   ```
+   # 配置文件示例：ou.logs.properties
+   ou.org.bmodule=组织机构
+   ou.emp.fmodule=人员维护
+   ou.emp.create=新增人员
+   ou.emp.create.message=新增人员[{}]
+   ou.emp.update=编辑人员
+   ou.emp.delete=删除人员
+   ou.emp.delete.message=删除人员{}
+   ```
+
+   搭配LogPattenUtils进行获取使用：
+
+   ```
+   LogPattenUtils.getProperty("ou.org.bmodule")
+   ```
+
+5. **日志对象构建与记录**
+
+   // 新增日志
+   Message msg = new Message(操作类型,业务模块,功能模块,操作说明,操作信息,操作状态);
+   logPostService.postLog(msg);
+   
+   ```java
+   // 新增日志
+   Message msg = new Message(Message.TYPE_OPT,
+           LogPattenUtils.getProperty("ou.org.bmodule"),        // 业务模块
+           LogPattenUtils.getProperty("ou.emp.fmodule"),       // 功能模块
+           LogPattenUtils.getProperty("ou.emp.create"),        // 操作说明
+           StrUtil.format(LogPattenUtils.getProperty("ou.emp.create.message"), emp.getName()), // 操作信息
+           Message.STATUS_SUCESS);                              // 操作状态
+   logPostService.postLog(msg);
+   
+   // 编辑日志（自动对比变更）
+   Emp empDb = service.getEmpById(emp.getId());
+   String compareLog = CompareUtils.getCompareLog(empDb, emp);  // 自动生成变更日志
+   Message msg = new Message(Message.TYPE_OPT,
+           LogPattenUtils.getProperty("ou.org.bmodule"),
+           LogPattenUtils.getProperty("ou.emp.fmodule"),
+           LogPattenUtils.getProperty("ou.emp.update"),
+           compareLog,
+           Message.STATUS_SUCESS);
+   logPostService.postLog(msg);
+   
+   // 删除日志
+   Message msg = new Message(Message.TYPE_OPT,
+           LogPattenUtils.getProperty("ou.org.bmodule"),
+           LogPattenUtils.getProperty("ou.emp.fmodule"),
+           LogPattenUtils.getProperty("ou.emp.delete"),
+           StrUtil.format(LogPattenUtils.getProperty("ou.emp.delete.message"),  emp.getName()),
+           Message.STATUS_SUCESS);
+   logPostService.postLog(msg);
+   ```
+
+###### 3.1.1.1. **Message 参数说明**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| type | String | 是 | 日志类型：0-操作日志，1-访问日志，2-登录日志，3-错误日志，5-安全日志，6-服务日志，7-登出日志 |
+| bmodule | String | 是 | 业务模块 |
+| fmodule | String | 是 | 功能模块 |
+| operation | String | 是 | 操作描述，如"新增"、"编辑"、"删除" |
+| message | String | 否 | 日志内容/变更详情 |
+| status | String | 是 | 操作状态：1-成功，0-失败 |
+
+###### 3.1.1.2.**@LogDesc 实体字段注解**
+
+完整包路径：`com.meritdata.cloud.base.LogDesc`
+
+用于标注实体类字段，配合 `CompareUtils` 自动生成变更日志。
+
+```java
+@Target({ElementType.FIELD, ElementType.TYPE})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface LogDesc {
+    String value() default "";           // 字段中文描述
+    String keyField() default "";         // 主键列名（用于生成日志前缀）
+    String[] relationField() default {};  // 关系列
+    String relationWord() default "";     // 关系列拼接字符
+    String lookupType() default "";       // 数据字典类型（自动转换编码为标签）
+    String moduleType() default "";      // 自定义字段MODULE_TYPE
+    String[] typeCustom() default {};    // 自定义类型映射
+    boolean booleanFlag() default false;  // 布尔类型转换标识
+    boolean changeFlag() default false;   // 变更类型标识（打印"XX变更"）
+    boolean themType() default false;    // 主题类型标识
+}
+```
+
+**相关注解**：
+- `@AddDesc` - 标记新增操作需要记录的字段
+
+- `@DelDesc` - 标记删除操作需要记录的字段
+
+  changeFlag = true时，打印："${字段描述}"变更
+
+**@LogDesc 实体类配置示例**
+
+来源：`Emp.java` - 人员实体类
+
+```java
+@LogDesc(value = "人员", keyField = "name")
+@Entity
+@Table(name = "[PF_ORG_USER]")
+public class Emp extends CloudBaseEntity implements Serializable {
+
+    @Id
+    @Column(name = "[ID]", length = 32)
+    private String id;
+
+    @Column(name = "[NAME]", length = 200)
+    @LogDesc("姓名")        // 字段描述
+    @DelDesc               // 删除时记录此字段
+    @AddDesc               // 新增时记录此字段
+    private String name;
+
+    @Column(name = "[CODE]")
+    @LogDesc("编码")
+    private String code;
+
+    @Column(name = "[SEX]")
+    @LogDesc(value = "性别", lookupType = "sex")  // lookupType自动转换数据字典
+    private Integer sex;
+
+    @Column(name = "[HANDSET]", length = 256)
+    @LogDesc(value = "手机号", changeFlag = true)  // changeFlag=true打印"手机号变更"
+    private String handset;
+
+    @Column(name = "[CARD]", length = 60)
+    @LogDesc(value = "身份证号码", changeFlag = true)
+    private String card;
+}
+```
+
+**CompareUtils 自动生成变更日志**
+
+完整包路径：`com.meritdata.cloud.log.compare.CompareUtils`
+
+```java
+// 对比两个实体对象，生成变更日志
+// 格式：编辑人员[张三]: "姓名"由[张三]变更为[李四], "编码"由[001]变更为[002]
+String compareLog = CompareUtils.getCompareLog(oldEmp, newEmp);
+
+// 示例输出：
+// 编辑人员[张三]: "姓名"由[张三]变更为[李四], "性别"由[男]变更为[女], "手机号"变更
+```
+
+---
+
+###### 3.1.1.3.**@LogOperation 注解说明**
+
+完整包路径：`com.meritdata.cloud.log.aspect.LogOperation`
+
+```java
+@Target({ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+public @interface LogOperation {
+    /**
+     * 操作类型
+     */
+    String type() default "select";
+}
+```
+
+**type 参数可选值**：
+
+| 值 | 说明 |
+|---|---|
+| add | 新增 |
+| edit | 修改 |
+| delete | 删除 |
+| select | 查询 |
+| visit | 访问 |
+| loginIn | 登录 |
+| loginOut | 登出 |
+| import | 导入 |
+| export | 导出 |
+| download | 下载 |
+| upload | 上传 |
+| assign | 分配/变更 |
+
+---
+
+###### 3.1.1.4.**使用示例：**
+
+公共src\main\resources\logs\ou.logs.properties
+
+```
+
+## 💡 使用建议
+- **注入而非 new**：必须通过 `@Autowired private ILogPostService logPostService;` 注入使用，平台日志走 Feign 远程调用，独立 new 实例无法命中拦截器。
+- **变更日志三件套**：实体类加 `@LogDesc`、Service 取旧值、Controller 调 `CompareUtils.getCompareLog(oldEntity, newEntity)` —— 三者缺一不可。
+- **敏感字段加 `changeFlag = true`**：身份证号 / 手机号 / 邮箱等敏感字段必须 `changeFlag = true`，日志只打印"XX变更"不打印具体值，避免泄密。
+- **`logPostService.postLog()` vs `logPostService.postDiyLog()`**：标准审计/操作日志用 `postLog`；自定义登录/登出等业务侧日志用 `postDiyLog`（见 07 拆分文件示例）。
+
+## 🔗 相关章节
+- 07_三平台服务-3.1日志注解-LogDesc-LogOperation.md