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

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

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

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