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

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

@@ -0,0 +1,82 @@
+## 前置条件
+
+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 对称加密
+
+只使用由已批准配置或密钥服务提供的密钥。不要调用依赖库的默认密钥重载，也不要把密钥、私钥或解密后的值写入代码、文档或日志。
+
+在生成代码前确认目标项目的密钥轮换、密文格式和 `Sm4Utils` 方法签名。前后端组合解密仅在已有平台协议明确要求时使用。
+
+---
+
+## 加解密注意事项
+
+1. `SM3Encoder` 没有 `encrypt()` 方法，使用 `encryptWithHMacMD5()` 或 `encode()`
+2. 不记录、打印或提交密钥和令牌；生产密钥必须可轮换并受访问控制。
+3. 先用现有集成测试验证加密、解密和错误密钥处理，再接入业务接口。
+
+---

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

@@ -0,0 +1,49 @@
+## 前置条件
+
+Maven 依赖已包含在 `cloud-starter-core` 基础包中，二开项目继承平台脚手架后自动引入，无需额外配置。
+
+## 原理
+
+基于 Hibernate `@Filter` 实现。只有目标项目已注册相应拦截器、当前会话带有密级信息且查询路径启用了过滤时，`@EnableDataSecretFilter` 才能生效。
+
+**过滤规则**: 用户只能看到**低于或等于**其自身密级的数据，高于用户密级的数据被自动拦截。
+
+---
+
+## 使用方式
+
+### 方法级别标注
+
+在需要过滤的查询方法上添加 `@EnableDataSecretFilter`：
+
+```java
+@LogOperation(type = "select")
+@EnableDataSecretFilter
+public List<Emp> selectEmpList() {
+    return empRepository.findAll();
+}
+```
+
+### 使用前验证
+
+先查看目标项目中 `@EnableDataSecretFilter` 的已有用法，确认该版本支持的方法或类型目标。不要仅根据实体上的 `@FilterDef` 假定运行时过滤已启用。
+
+---
+
+## 完整包路径
+
+| 类/注解 | 路径 |
+|---------|------|
+| `@EnableDataSecretFilter` | `com.meritdata.cloud.base.tenancy.EnableDataSecretFilter` |
+| `DataSecretInterceptor` | 系统自动注册的拦截器，无需手动配置 |
+
+---
+
+## 密级过滤注意事项
+
+1. 数据密级过滤只在查询时生效，**不阻止手动写入高密级数据**
+2. 依赖当前用户会话中的密级信息，确保 SessionUtils 正常工作
+3. 不得通过省略注解作为通用绕过方式；特权查看必须走已授权、可审计的独立路径。
+4. 至少验证一个允许访问和一个拒绝访问的密级用例。
+
+---

package/skills/meritdata-platform-core/references/logging.md

@@ -0,0 +1,256 @@
+## 前置条件
+
+Maven 依赖已包含在 `cloud-starter-core` 基础包中，二开项目继承平台脚手架后自动引入。
+
+**服务调用方式**: Feign 远程调用，服务名 `cloud-system-manage`，基础路径 `/api/basic/log`。
+
+引入 Feign 依赖后注入使用：
+
+```java
+@Autowired
+private ILogPostService logPostService;
+```
+
+**完整包路径**: `com.meritdata.cloud.log.service.ILogPostService`
+
+---
+
+## 快速开始：新增日志
+
+```java
+Message msg = new Message(
+    Message.TYPE_OPT,          // 日志类型：0-操作日志
+    "组织机构",                  // 业务模块
+    "人员维护",                  // 功能模块
+    "新增人员",                  // 操作描述
+    "新增人员[张三]",            // 日志内容
+    Message.STATUS_SUCESS       // 状态：1-成功
+);
+logPostService.postLog(msg);
+```
+
+输出日志：`[用户1:user1] 新增人员[张三]`
+
+---
+
+## 日志类型
+
+| 常量 | 值 | 说明 |
+|------|-----|------|
+| `Message.TYPE_OPT` | 0 | 操作日志 |
+| `Message.TYPE_VISIT` | 1 | 访问日志 |
+| `Message.TYPE_LOGIN` | 2 | 登录日志 |
+| `Message.TYPE_ERROR` | 3 | 错误日志 |
+| `Message.TYPE_SAFE` | 5 | 安全日志 |
+| `Message.TYPE_SERVER` | 6 | 服务日志 |
+| `Message.TYPE_LOGOUT` | 7 | 登出日志 |
+
+---
+
+## Message 对象
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| type | String | 是 | 日志类型 |
+| bmodule | String | 是 | 业务模块 |
+| fmodule | String | 是 | 功能模块 |
+| operation | String | 是 | 操作描述 |
+| message | String | 否 | 日志内容/变更详情 |
+| status | String | 是 | 操作状态：1-成功 |
+
+可选字段：`ip`, `fullname`, `userid`, `tenantId`, `grade`, `code`, `operationType`, `startTime`, `endTime`, `executeTime`
+
+---
+
+## 日志模板配置
+
+在 `src/main/resources/logs/{module}.logs.properties` 中配置：
+
+```properties
+# 业务模块
+ou.org.bmodule=组织机构
+# 功能模块
+ou.emp.fmodule=人员维护
+# 操作描述
+ou.emp.create=新增人员
+# 操作信息模板（{}为占位符）
+ou.emp.create.message=新增人员[{}]
+ou.emp.update=编辑人员
+ou.emp.delete=删除人员
+ou.emp.delete.message=删除人员{}
+```
+
+读取配置：
+
+```java
+LogPattenUtils.getProperty("ou.org.bmodule")
+```
+
+---
+
+## @LogDesc — 实体字段注解
+
+**完整包路径**: `com.meritdata.cloud.base.LogDesc`
+
+注解在实体类上，配合 `CompareUtils` 自动生成变更日志。
+
+```java
+@LogDesc(value = "人员", keyField = "name")  // 类注解：实体描述 + 日志主键字段
+@Entity
+public class Emp extends CloudBaseEntity {
+
+    @LogDesc("姓名")        // 普通字段：变更显示"姓名"由[旧值]变更为[新值]
+    @DelDesc               // 删除时记录此字段
+    @AddDesc               // 新增时记录此字段
+    private String name;
+
+    @LogDesc(value = "性别", lookupType = "sex")  // lookupType 自动转换数据字典
+    private Integer sex;
+
+    @LogDesc(value = "手机号", changeFlag = true)  // changeFlag=true 显示"手机号变更"
+    private String handset;
+}
+```
+
+| 属性 | 说明 |
+|------|------|
+| `value` | 字段中文描述 |
+| `keyField` | 日志前缀字段名（类上使用） |
+| `lookupType` | 数据字典类型，自动转换编码为中文 |
+| `changeFlag` | true → 打印"XX变更"，不显示具体值（敏感信息） |
+| `booleanFlag` | 布尔类型转换 |
+
+**配套注解**：
+- `@AddDesc` — 标记新增时记录此字段
+- `@DelDesc` — 标记删除时记录此字段
+
+---
+
+## CompareUtils — 自动变更日志
+
+**完整包路径**: `com.meritdata.cloud.log.compare.CompareUtils`
+
+```java
+Emp empDb = service.getEmpById(emp.getId());
+// 自动生成："姓名"由[张三]变更为[李四], "性别"由[男]变更为[女], "手机号"变更
+String compareLog = CompareUtils.getCompareLog(empDb, emp);
+```
+
+---
+
+## 完整 CRUD 日志示例
+
+### 新增
+
+```java
+@LogOperation(type = "add")
+public boolean create(Emp emp) {
+    boolean flag = service.insertEmp(emp);
+    if (flag) {
+        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);
+    }
+    return flag;
+}
+```
+
+### 编辑
+
+```java
+@LogOperation(type = "edit")
+public boolean update(Emp emp) {
+    Emp empDb = service.getEmpById(emp.getId());
+    String compareLog = CompareUtils.getCompareLog(empDb, emp);
+    boolean flag = service.updateEmp(emp);
+    if (flag && StrUtil.isNotBlank(compareLog)) {
+        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);
+    }
+    return flag;
+}
+```
+
+### 删除
+
+删除日志必须在删除前或删除结果中取得已删除对象的可审计摘要。不要复制使用未定义变量的“完整示例”；沿用目标项目已存在的删除日志实现，并避免记录密码、令牌或完整敏感字段。
+
+---
+
+## @LogOperation — 方法注解
+
+**完整包路径**: `com.meritdata.cloud.log.aspect.LogOperation`
+
+标记方法操作类型，框架自动记录操作时间。
+
+| type 值 | 说明 |
+|---------|------|
+| `add` | 新增 |
+| `edit` | 修改 |
+| `delete` | 删除 |
+| `select` | 查询 |
+| `visit` | 访问 |
+| `loginIn` | 登录 |
+| `loginOut` | 登出 |
+| `import` | 导入 |
+| `export` | 导出 |
+| `download` | 下载 |
+| `upload` | 上传 |
+| `assign` | 分配/变更 |
+
+```java
+@LogOperation(type = "add")
+public ReturnT<String> add(@Valid CloudJobInfo jobInfo) {
+    Message msg = new Message(...);
+    msg.setStartTime(System.currentTimeMillis());
+    msg.setEndTime(System.currentTimeMillis());
+    logPostService.postLog(msg);
+    return CloudJobService.add(jobInfo);
+}
+```
+
+---
+
+## 自定义日志 (postDiyLog)
+
+**接口**: `POST /post-diy`
+
+```java
+private void postLoginLog(User user, Long startTime) {
+    Long executeTime = System.currentTimeMillis() - startTime;
+    Message msg = new Message(Message.TYPE_LOGOUT,
+        LogPattenUtils.getProperty("common.basic.bmodule"),
+        LogPattenUtils.getProperty("common.logout.fmodule"),
+        LogPattenUtils.getProperty("common.logout.fmodule"),
+        StrUtil.format(LogPattenUtils.getProperty("common.loginout.user")),
+        Message.STATUS_SUCESS);
+    msg.setIp(user.getLoginIp());
+    msg.setFullname(user.getUsername());
+    msg.setUserid(user.getUserId());
+    msg.setTenantId(user.getTenantId());
+    msg.setCode(user.getCode());
+    msg.setOperationType("loginOut");
+    msg.setExecuteTime(executeTime);
+    logPostService.postDiyLog(msg);
+}
+```
+
+---
+
+## 日志注意事项
+
+1. 日志服务是 Feign 远程调用，需要确保 `cloud-system-manage` 服务可用
+2. 日志模板文件必须放在 `src/main/resources/logs/` 目录
+3. `@LogDesc` 的 `changeFlag=true` 用于敏感字段，不暴露具体值
+4. `@LogOperation` 不自动记录日志内容，只辅助记录时间和类型
+
+---

package/skills/meritdata-platform-core/references/nacos.md

@@ -0,0 +1,140 @@
+## 前置条件
+
+Maven 依赖已包含在 `cloud-starter-core` 基础包中，二开项目继承平台脚手架后自动引入，无需额外配置。
+
+## 重要：注入方式
+
+**`NacosUtils` 不是静态工具类**，它是 Spring Bean，必须通过 `@Autowired` 注入：
+
+```java
+@Autowired
+private NacosUtils nacosUtils;
+```
+
+**完整包路径**: `com.meritdata.cloud.utils.NacosUtils`
+
+---
+
+## 写入安全要求
+
+默认只读。修改、重置或清空配置前，必须确认目标环境、namespace/group、dataId、调用权限和回滚方式；先读取并保存原内容，再比较差异，写入后回读验证。
+
+不得生成用于清空整份配置的默认代码。令牌只可在运行时受管使用，不得输出到日志、文档或提交物。
+
+---
+
+## API 参考
+
+### 读取配置
+
+#### getConfigList(dataId) → Map
+
+获取指定配置文件的所有配置项。
+
+```java
+Map configMap = nacosUtils.getConfigList("common-cloud-system-manage.properties");
+```
+
+#### getConfigFile(dataId) → String
+
+获取指定配置文件的完整内容。
+
+```java
+String content = nacosUtils.getConfigFile("application.properties");
+```
+
+#### getConfigValue(dataId, configKey) → String
+
+获取单个配置项的值。
+
+```java
+String value = nacosUtils.getConfigValue(
+    "common-cloud-system-manage.properties",
+    "meritdata.cloud.security-label-show"
+);
+```
+
+#### getAllConfigFile() → Map\<String, String\>
+
+获取所有配置文件的键值对。
+
+```java
+Map<String, String> all = nacosUtils.getAllConfigFile();
+```
+
+### 修改配置
+
+#### updateConfig(dataId, configKey, configValue) → boolean
+
+修改单个配置项。
+
+```java
+boolean ok = nacosUtils.updateConfig(
+    "common-cloud-system-manage.properties",
+    "meritdata.cloud.security-label-show",
+    "true"
+);
+```
+
+#### updateConfigFile(dataId, content) → boolean
+
+更新整个配置文件内容。
+
+仅在完成快照、差异检查和显式确认后调用。
+
+### 新增配置
+
+#### addConfig(dataId, configKey, configValue) → boolean
+
+```java
+nacosUtils.addConfig("custom.properties", "custom.key", "value");
+```
+
+### 重置/清除
+
+#### reSetConfigFile(dataId, content) → boolean
+
+重置配置文件内容。
+
+#### clearConfigFile(dataId) → boolean
+
+清除配置文件的所有内容。
+
+这是破坏性操作，仅在明确授权、已备份且有回滚方案时执行。
+
+### Token
+
+#### getNacosToken() → String
+
+获取 Nacos 访问令牌。
+
+```java
+String token = nacosUtils.getNacosToken();
+```
+
+---
+
+## Nacos 方法速查表
+
+| 方法 | 入参 | 返回 | 说明 |
+|------|------|------|------|
+| `getConfigList` | dataId | Map | 获取配置项列表 |
+| `getConfigFile` | dataId | String | 获取完整文件内容 |
+| `getConfigValue` | dataId, configKey | String | 获取单个配置值 |
+| `getAllConfigFile` | 无 | Map\<String, String\> | 获取所有配置 |
+| `updateConfig` | dataId, key, value | boolean | 修改配置项 |
+| `updateConfigFile` | dataId, content | boolean | 更新整个文件 |
+| `addConfig` | dataId, key, value | boolean | 新增配置项 |
+| `reSetConfigFile` | dataId, content | boolean | 重置文件 |
+| `clearConfigFile` | dataId | boolean | 清除文件 |
+| `getNacosToken` | 无 | String | 获取 Token |
+
+---
+
+## Nacos 注意事项
+
+1. **必须通过 @Autowired 注入**，不能直接 `NacosUtils.xxx()` 静态调用
+2. 所有修改类方法返回 boolean 表示操作是否成功；写入后仍需回读验证
+3. dataId 为 Nacos 上的配置文件标识，通常是 `.properties` 文件名
+
+---

package/skills/meritdata-platform-core/references/session.md

@@ -0,0 +1,125 @@
+## 前置条件
+
+Maven 依赖已包含在 `cloud-starter-core` 基础包中，二开项目继承平台脚手架后自动引入，无需额外配置。
+
+---
+
+## SessionUtils — 会话工具类
+
+**完整包路径**: `com.meritdata.cloud.utils.SessionUtils`
+
+通过依赖注入使用：
+
+```java
+@Autowired
+private SessionUtils sessionUtils;
+```
+
+> **注意**: `getUserName()` 和 `getCurrentUserName()` 方法均可用，返回相同结果。
+
+### 用户信息
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getUserId()` | String | 用户 ID（`pf_user_info.id`） |
+| `getUserName()` | String | 用户名 |
+| `getCurrentUserName()` | String | 用户名（同 getUserName） |
+| `getPrincipal()` | User | 整个用户对象 |
+
+```java
+String userId = sessionUtils.getUserId();
+String userName = sessionUtils.getUserName();
+User user = sessionUtils.getPrincipal();
+```
+
+### 人员信息
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getEmpId()` | String | 人员 ID（`pf_org_user.id`） |
+| `getEmpName()` | String | 人员姓名 |
+| `getEmpCode()` | String | 人员编号 |
+
+```java
+String empId = sessionUtils.getEmpId();
+String empName = sessionUtils.getEmpName();
+String empCode = sessionUtils.getEmpCode();
+```
+
+### 部门信息
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getDeptId()` | String | 部门 ID |
+| `getDeptCode()` | String | 部门编码 |
+| `getDeptName()` | String | 部门名称 |
+| `getDept()` | Organization | 部门对象 |
+
+```java
+String deptId = sessionUtils.getDeptId();
+Organization dept = sessionUtils.getDept();
+String deptName = dept.getName();
+```
+
+### 组织信息
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getOrgId()` | String | 组织 ID |
+| `getOrgName()` | String | 组织名称 |
+| `getOrgDlevelCode()` | String | 组织层级编码 |
+| `getRootOrgId()` | String | 根组织 ID |
+| `getRootOrg()` | Organization | 根组织对象 |
+
+```java
+String orgId = sessionUtils.getOrgId();
+Organization rootOrg = sessionUtils.getRootOrg();
+```
+
+### 角色与权限
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getSysRoleCodes()` | List\<String\> | 系统角色编码列表 |
+| `getRoleCodes()` | List\<String\> | 所有角色编码列表 |
+| `getRoleNames()` | List\<String\> | 所有角色名称列表 |
+| `getAuthoritiesIds()` | List\<String\> | 所有权限 ID 列表 |
+
+### 租户与登录信息
+
+| 方法 | 返回 | 说明 |
+|------|------|------|
+| `getTenantId()` | String | 租户 ID |
+| `getCurrentLoginIp()` | String | 当前登录 IP |
+
+---
+
+## IUserOnlineTime — 在线用户管理
+
+**完整包路径**: `com.meritdata.cloud.security.sso.IUserOnlineTime`
+
+Feign 客户端接口，通过依赖注入使用：
+
+```java
+@Autowired
+private IUserOnlineTime iUserOnlineTime;
+```
+
+### 踢出在线用户
+
+**接口**: `POST /api/basic/online-account/getOutOnlineByUserNames`
+
+批量踢出指定用户名的在线用户，清除其所有会话信息。
+
+这是高影响操作。调用前确认操作权限、目标用户名和业务影响，并记录操作者、原因与结果。
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| userNames | String | 用户名，多个用逗号分隔 |
+
+---
+
+## 会话注意事项
+
+1. `SessionUtils` 通过 `@Autowired` 注入，不是静态工具类
+2. `IUserOnlineTime` 是 Feign 远程调用，踢出操作会记录登录日志（`loginOut` 类型）

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

@@ -0,0 +1,62 @@
+---
+name: meritdata-platform-crypto-gm
+description: MeritData 国密算法专项。用于 SM2（非对称）、SM3（摘要）、SM4（对称）加解密；密钥管理；硬件加密机对接。
+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
+
+**国密密钥必须来自 KMS 硬件加密机，源码中不得出现密钥明文；SM3 用于密码摘要，禁止明文存储。**
+
+## 触发条件 / 不适用
+
+**适用**：
+- SM2 非对称加解密
+- SM3 摘要（密码存储）
+- SM4 对称加解密
+
+**不适用**：
+- 通用加密工具 → `meritdata-platform-core/references/crypto.md`
+
+## 主题路由
+
+### 公司级研发攻略（dev-docs 整合）
+
+| 攻略 | 内容 | 入口 |
+|------|------|------|
+| **攻略06：系统认证（6 章）** | token 认证集成、CAS 统一认证中心、第三方认证 | [`references/auth/攻略-06-系统认证-00_总览.md`](../meritdata-platform-sso/references/auth/攻略-06-系统认证-00_总览.md) |
+
+### 公共资产清单（公司级参考资料）
+
+| 内容 | 入口 |
+|------|------|
+| SM2/SM3/SM4 加解密（5_二通用工具） | [`references/assets/05_二通用工具-2.1加解密-SM2-SM3-SM4.md`](references/assets/05_二通用工具-2.1加解密-SM2-SM3-SM4.md) |
+
+## 工作方式
+
+1. SM2 用于身份认证、数据签名
+2. SM3 用于密码哈希（替代 MD5/SHA-1）
+3. SM4 用于敏感数据对称加密
+4. 密钥通过 KMS 加密机获取，**绝不硬编码**
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 密钥硬编码 | 安全漏洞 | KMS 加密机 |
+| 明文存密码 | 数据泄露 | SM3 摘要 |
+| MD5 存密码 | 易破解 | SM3 + salt |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 通用加密 → `meritdata-platform-core/references/crypto.md`
+  - 数据密级 → `meritdata-platform-data-secret`
+- **强制要求**：密钥必须来自 KMS