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

package/skills/meritdata-platform-core/references/assets/17_/351/231/204/345/275/225-/347/273/237/350/256/241/346/261/207/346/200/273-Maven/344/276/235/350/265/226-/346/263/250/346/204/217/344/272/213/351/241/271.md

@@ -0,0 +1,131 @@
+---
+name: 附录-统计汇总-Maven依赖-注意事项
+source-file: 公共资产清单
+source-section: 附录 - 组件及方法统计 + 统计汇总 + A. Maven依赖坐标 + B. 组件开发注意事项
+keywords: [Maven依赖, 命名规范, 注意事项, 组件统计, cloud-module-base, cloud-module-cache, cloud-starter-core, 6.13.2, EventBus, i18n, Element-UI]
+use-cases: [添加Maven依赖, 了解平台组件统计, 二开组件开发注意事项, 国际化引入, 依赖版本对齐]
+related: [17, 01]
+---
+
+# 附录-统计汇总-Maven依赖-注意事项
+
+> **原文章节**：`公共资产清单 → 组件及方法统计 + 统计汇总 + A. Maven依赖坐标 + B. 组件开发注意事项`
+> **行号范围**：L3416–L3516
+
+## 🎯 一句话
+汇总平台 43 个组件/工具类、111+ 方法的统计信息，以及二开项目接入必须引入的 Maven 依赖坐标与组件开发注意事项。
+
+## 📋 接口/方法清单
+
+## 组件及方法统计
+
+本文档共涵盖 **9个后端工具类**、**7个后端组件**、**7组外部接口**、**14个前端组件**、**6个前端工具方法**，共计 **43个组件/工具类**，包含 **111+个方法**。
+
+---
+
+| 分类 | 序号 | 名称 | 方法数 | 作用说明 |
+|------|------|------|--------|----------|
+| **后端工具类** | 1 | SysCacheServiceFacade | 23 | Redis缓存操作工具类，提供put/get/hget/hset/queue等23种缓存操作方法 |
+| | 2 | StringCacheFacade | 3 | String类型缓存工具类，提供put/get/multiGet方法 |
+| | 3 | NacosUtils | 10 | Nacos配置中心工具类，提供获取/修改/新增配置等10种方法 |
+| | 4 | Sm2Utils | 3 | SM2非对称加密工具类，提供密钥生成/加密/解密3种方法 |
+| | 5 | SM3Encoder | 2 | SM3哈希加密工具类，提供encryptWithHMacMD5/encode方法 |
+| | 6 | Sm4Utils | 2 | SM4对称加密工具类，提供encrypt/decrypt方法 |
+| | 7 | SessionUtils | 21 | 会话信息工具类，提供获取当前用户ID/姓名/部门/角色等21种方法 |
+| | 8 | LogPattenUtils | 1 | 日志模板工具类，提供getProperty获取日志模板配置 |
+| | 9 | CompareUtils | 1 | 日志对比工具类，提供getCompareLog自动生成变更日志 |
+| **后端组件** | 1 | ILogPostService | 2 | 日志服务组件，提供postLog/POST /post（操作日志）、postDiyLog/POST /post-diy（自定义日志）2个接口 |
+| | 2 | BpmEngine | 13 | 工作流引擎组件，提供启动流程/完成任务/退回/删除/查询/追踪等13个接口 |
+| | 3 | IJobApi | 10 | 任务调度组件，提供getJob/pageList/triggerJob/startJob/stopJob/add/update/remove等10个接口 |
+| | 4 | CloudFeignMessageClient | 5 | 服务通知Feign客户端，提供sendRoleMessage/sendResourceMessage/sendUserRoleMessage/sendAssignMessage/sendUserAppMessage 5个消息发送方法 |
+| | 5 | @LogDesc/@AddDesc/@DelDesc | 3 | 日志注解组件，@LogDesc标注字段描述、@AddDesc新增记录、@DelDesc删除记录 |
+| | 6 | EnableDataSecretFilter | 1 | 数据脱敏注解组件，标注后自动启用Hibernate数据密级过滤 |
+| | 7 | DynamicCloudFeignClient | 1 | 动态FeignClient构建组件，提供getFeignClient动态构建Feign客户端 |
+| **外部接口** | 1 | ISecurityAuthService | 7 | 安全认证接口，提供用户认证、权限查询等7个方法 |
+| | 2 | ICloudClient | 4 | 云服务客户端接口，提供服务端注册/心跳等4个方法 |
+| | 3 | IJobApi | 10 | 任务调度API接口，提供任务CRUD/触发/启停等10个方法 |
+| | 4 | IMessageApi | 3 | 消息服务接口，提供消息发送等3个方法 |
+| | 5 | IResourceApi | 4 | 资源管理接口，提供资源查询/分配等4个方法 |
+| | 6 | IUserPortalApi | 3 | 用户门户接口，提供用户信息/Token等3个方法 |
+| | 7 | 其他Feign接口 | - | 包含ISysLogApi、IOrgApi、IEmpApi等若干Feign接口 |
+| **前端组件** | 1 | CloudDialog | - | 通用对话框组件，提供对话框显示/关闭等交互 |
+| | 2 | UserSelect | - | 用户选择组件，通过props控制选择模式，通过events交互 |
+| | 3 | UserSelectMulti | - | 多用户选择组件，通过props控制选择模式，通过events交互 |
+| | 4 | DeptSelect | - | 部门选择组件，通过props控制选择模式，通过events交互 |
+| | 5 | RoleSelect | - | 角色选择组件，通过props控制选择模式，通过events交互 |
+| | 6 | ImportButton | - | 导入按钮组件，支持导入模板下载/数据导入/错误文件下载，通过events交互 |
+| | 7 | MenuAuth | - | 菜单权限组件，通过props控制权限显示 |
+| | 8 | ResourceCodeAuth | - | 资源权限组件，通过props控制资源权限显示 |
+| | 9 | ThreeMemberAuth | - | 三员授权组件，通过props和events与外部交互 |
+| | 10 | TableHeadSearch | - | 表格头部搜索组件 |
+| | 11 | VerifiyPassword | - | 二级鉴别密码验证弹窗组件 |
+| | 12 | CommonHeader | - | 通用头部组件 |
+| | 13 | BpmGridButtonsNew | - | BPM表格按钮组件，提供新建/我的申请/我的审批/所有流程等操作按钮，通过props和events与外部交互 |
+| | 14 | BpmFormTools | - | BPM表单工具组件，集成发送/暂存等流程操作按钮 |
+| **前端工具方法** | 1 | sm4-utils.js | 2 | SM4加密解密工具，提供encrypt/decrypt方法 |
+| | 2 | sm2.js | - | SM2加密工具 |
+| | 3 | accessLogs.js | 1 | 访问日志工具，提供saveAcessLog方法 |
+| | 4 | dataFormat.js | 1 | 日期格式化工具，提供formatter方法 |
+| | 5 | form-rules.js | 12 | 表单校验规则，提供required/nospecial/noSpecialCode/name/cellphone/telephone/email/idcard/url/ip/mac等12种校验规则 |
+| | 6 | globalValitor.js | - | 全局校验器 |
+
+---
+
+### 统计汇总
+
+| 分类 | 数量 | 方法/接口数 |
+|------|------|-------------|
+| 后端工具类 | 9个 | 66个方法 |
+| 后端组件 | 7个 | 25个接口 |
+| 外部接口 | 7组 | 20+个接口 |
+| 前端组件 | 14个 | - |
+| 前端工具方法 | 6个 | - |
+| **合计** | **43个** | **111+个** |
+
+---
+
+### A. Maven依赖坐标
+
+```xml
+<!-- cloud-module-base -->
+<dependency>
+    <groupId>com.meritdata.cloud</groupId>
+    <artifactId>cloud-module-base</artifactId>
+    <version>6.13.2</version>
+</dependency>
+
+<!-- cloud-module-cache -->
+<dependency>
+    <groupId>com.meritdata.cloud</groupId>
+    <artifactId>cloud-module-cache</artifactId>
+    <version>6.13.2</version>
+</dependency>
+
+<!-- cloud-starter-core -->
+<dependency>
+    <groupId>com.meritdata.cloud</groupId>
+    <artifactId>cloud-starter-core</artifactId>
+    <version>6.13.2</version>
+</dependency>
+```
+
+---
+
+### B. 组件开发注意事项
+
+1. **EventBus**: 所有组件通过 `Vue.prototype.EventBus` 进行内部通信
+2. **国际化**: 组件使用 `$t()` 函数进行国际化处理，需要配置 i18n
+3. **依赖**: BPM 组件依赖 Element-UI 和 cloud-module-base
+4. **样式**: CloudDialog 组件需要引入样式文件: `import 'cloud-module-base/static/css/cloud-dialog.css';`
+
+## 💡 使用建议
+
+1. **版本锁定**：所有 `cloud-module-*` 依赖固定 `6.13.2`，与 `pom.xml` 中 `meritdata-platform-cloud.version` 一致，避免序列化错误。
+2. **BPM 组件强依赖**：BPM 相关组件（`BpmFormTools` / `BpmGridButtonsNew`）必须额外引入 `cloud-module-bpm`，否则页面报错。
+3. **国际化必须**：所有 `$t()` 文案必须新增 i18n 词条，否则会渲染 `key` 字符串。
+4. **不要重复造轮子**：优先调用平台服务（如 `SysCacheServiceFacade`），不要直接用 `RedisTemplate`；优先使用 `cloud-module-base` 静态组件，不要自研。
+
+## 🔗 相关章节
+
+- `01_全部章节`（其他所有拆分文件）
+- `公共资产清单 5.3 流程组件与方法`（MeritBPM 前端方法与后端 API 对应）

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

@@ -0,0 +1,237 @@
+## 前置条件
+
+Maven 依赖已包含在 `cloud-starter-core` 基础包中，二开项目继承平台脚手架后自动引入，无需额外配置。
+
+## 快速开始
+
+```java
+// 写入缓存（永不过期）
+SysCacheServiceFacade.put("key", value);
+
+// 写入缓存（带过期时间，秒）
+SysCacheServiceFacade.putExpire("key", value, 3600);
+
+// 读取缓存
+Object value = SysCacheServiceFacade.get("key");
+
+// 判断是否存在
+boolean exists = SysCacheServiceFacade.isExist("key");
+
+// 删除缓存
+SysCacheServiceFacade.remove("key");
+```
+
+---
+
+## SysCacheServiceFacade — 通用缓存操作
+
+**完整包路径**: `com.meritdata.tempo.syscache.service.SysCacheServiceFacade`
+
+**基于 2026-09-10 源码实测**：本类共 **42 个 public 静态方法**，可直接通过类名调用。存储 Object 类型。
+
+### 基本操作
+
+#### put(key, value)
+
+写入缓存，**永不过期**。适用于高频访问且不刷新的静态数据。
+
+```java
+SysCacheServiceFacade.put("user:session:" + userId, userSession);
+SysCacheServiceFacade.put("EXCEPTION_EVENT_SESSION" + username, allSessions);
+```
+
+#### putExpire(key, value, seconds)
+
+写入缓存并设置过期时间（秒）。适用于 token、临时数据。
+
+```java
+SysCacheServiceFacade.putExpire("nacosToken", accessToken, 14400);
+SysCacheServiceFacade.putExpire("temp:data:" + id, value, 3600);
+```
+
+#### putExpireAt(key, value, unixTime)
+
+在指定时间点过期，unixTime 为毫秒时间戳。**注意：底层会自动 +3000ms**。
+
+```java
+SysCacheServiceFacade.putExpireAt("event:expire", value, System.currentTimeMillis() + 3600000);
+```
+
+#### get(key) → Object
+
+```java
+Object session = SysCacheServiceFacade.get("user:session:" + userId);
+```
+
+#### isExist(key) → Boolean
+
+```java
+if (SysCacheServiceFacade.isExist("nacosToken")) { /* 刷新或使用 */ }
+```
+
+#### remove(key)
+
+```java
+SysCacheServiceFacade.remove("user:session:" + userId);
+```
+
+### Hash 操作
+
+#### hset(h, hkey, hvalue)
+
+将数据以 Hash 结构存储，常用于用户会话。
+
+```java
+SysCacheServiceFacade.hset("CACHE_SESSION_LIST_KEY", user.getUsername(), user);
+```
+
+#### hget(h, hkey) → Object
+
+```java
+User user = (User) SysCacheServiceFacade.hget("CACHE_SESSION_LIST_KEY", loginName);
+```
+
+#### hgetAll(key) → Map<String, Object>
+
+```java
+Map<String, Object> allUsers = SysCacheServiceFacade.hgetAll("CACHE_SESSION_LIST_KEY");
+```
+
+#### hkeys(h) → Set<String>
+
+```java
+Set<String> fields = SysCacheServiceFacade.hkeys("CACHE_SESSION_LIST_KEY");
+```
+
+#### hvalues(h) → List<Object>
+
+```java
+List<Object> values = SysCacheServiceFacade.hvalues("CACHE_SESSION_LIST_KEY");
+```
+
+#### hdel(h, hkey) → Long
+
+```java
+SysCacheServiceFacade.hdel("CACHE_SESSION_LIST_KEY", loginName);
+```
+
+### 批量操作
+
+#### multiGet(keys) → List<Object>
+
+```java
+List<Object> values = SysCacheServiceFacade.multiGet(Arrays.asList("k1", "k2", "k3"));
+```
+
+### 队列操作
+
+#### enqueue(key, value) → Long — 入队
+
+```java
+SysCacheServiceFacade.enqueue("task_queue", taskData);
+```
+
+#### dequeue(key) → Object — 出队
+
+```java
+Object data = SysCacheServiceFacade.dequeue("task_queue");
+```
+
+#### dequeueList(key) → List<Object> — 批量出队
+
+```java
+List<Object> batch = SysCacheServiceFacade.dequeueList("task_queue");
+```
+
+#### queueSize(key) → Long — 队列长度
+
+```java
+if (SysCacheServiceFacade.queueSize("task_queue") > 100) { /* 告警 */ }
+```
+
+### 计数器
+
+#### increment(k) / increment(k, delta) → Long
+
+```java
+SysCacheServiceFacade.increment("page:views");
+SysCacheServiceFacade.increment("request:count", 1);
+```
+
+#### decrement(k) / decrement(k, delta) → Long
+
+```java
+SysCacheServiceFacade.decrement("stock:count");
+```
+
+### 幂等与分布式锁
+
+`setIfAbsent` 的存在不代表它满足生产分布式锁要求。本资料未证明该 API 具有过期时间、持有者标识和 compare-and-delete 解锁语义，因此不要把它单独用作分布式锁。
+
+优先使用业务唯一约束或幂等键。确需锁时，先确认目标版本提供的原子 API，并同时满足过期时间、持有者 token、`finally` 释放和非持有者不可释放。
+
+#### getAndSet(k, v) → Object
+
+原子性获取旧值并设置新值。
+
+```java
+Object oldToken = SysCacheServiceFacade.getAndSet("user:token:" + userId, newToken);
+```
+
+### 发布订阅
+
+#### publish(channel, message)
+
+```java
+SysCacheServiceFacade.publish("channel:notify", JSON.toJSONString(event));
+```
+
+#### subscribe(channel, ICacheSubscribeListener)
+
+**注意参数顺序**:
+- 对外 API: `subscribe(channel, listener)` — channel 在前
+- 底层调用: `subscribe(listener, channel)` — listener 在前（内部自动调换）
+- 回调接口 `ICacheSubscribeListener.onMessage(msg)` **只接收一个参数 msg**
+
+```java
+SysCacheServiceFacade.subscribe("channel:notify", (msg) -> {
+    System.out.println("收到消息: " + msg);
+});
+```
+
+---
+
+## StringCacheFacade — String 专用缓存
+
+**完整包路径**: `com.meritdata.tempo.syscache.service.StringCacheFacade`
+
+**⚠️ 重要（基于 2026-09-10 源码实测）**：
+- 共 **31 个 public 方法**
+- 大部分方法为 `public static`（如 `put`/`get`/`multiGet`/`hset`/`hincrBy`/`del`/`publish`/`subscribe` 等），可直接通过类名调用
+- **但有 9 个方法是非 static 实例方法**，必须 `@Autowired` 注入后调用：
+  - `setIfAbsent(k, v)`
+  - `setIfPresent(k, v)`
+  - `increment(k)` / `increment(k, delta)`
+  - `decrement(k)` / `decrement(k, delta)`
+  - `append(k, v)`
+  - `size(k)`
+  - `getAndSet(k, v)`
+- 与 SysCacheServiceFacade 用法**不完全一致**，键值均为 String 类型。
+
+```java
+StringCacheFacade.put("config:version", "1.0.0");
+String version = StringCacheFacade.get("config:version");
+List<String> values = StringCacheFacade.multiGet(Arrays.asList("k1", "k2"));
+```
+
+---
+
+## 缓存注意事项
+
+1. `SysCacheServiceFacade` 存储 Object，取出时需要强制类型转换
+2. `StringCacheFacade` 只支持 String，无需类型转换
+3. `putExpireAt` 内部会自动 +3000ms
+4. `subscribe` 对外参数顺序和底层不一致，使用时注意
+5. 缓存键避免包含密码、令牌、身份证号或完整会话对象
+
+---

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. 至少验证一个允许访问和一个拒绝访问的密级用例。
+
+---