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

package/skills/{meritdata-dev-docs-file-finder/references/dev-docs → meritdata-platform-core/references/assets}/04_/344/270/200/345/237/272/347/241/200/350/256/276/346/226/275-1.2/351/205/215/347/275/256/344/270/255/345/277/203-NacosUtils.md

@@ -1,193 +1,193 @@
----
-name: 一基础设施-1.2配置中心-NacosUtils
-source-file: 公共资产清单
-source-section: 一、基础设施类 → 1.2 配置中心 → NacosUtils L518-L684
-keywords: [Nacos配置中心, NacosUtils, getConfigList, publishConfig, MeritdataCloudProperties, Spring Bean]
-use-cases: [动态读取Nacos配置, 修改Nacos配置, 配置文件批量更新, Nacos鉴权Token获取]
-related: [02_一基础设施-1.1缓存操作-SysCacheServiceFacade.md]
----
-
-# 1.2 配置中心 — NacosUtils
-
-> **原文章节**：`公共资产清单 → 一、基础设施类 → 1.2 配置中心 → NacosUtils`
-> **行号范围**：L518-L684
-
-## 🎯 一句话
-`NacosUtils` 提供 Nacos 配置的读写能力，对外暴露 10 个方法（基于 Spring Bean 注入），常用于运行时动态获取/修改配置。
-
-## 📋 接口/方法清单
-
-### 1.2 配置中心
-
-#### NacosUtils
-
-**注意**：`NacosUtils` **不是静态工具类**，它是一个Spring Bean，需要通过依赖注入获取实例。类上有`@DisableEncrypt`注解，但方法使用`@Autowired`注入`MeritdataCloudProperties`和`Environment`。
-
-**正确用法**（通过Spring注入）：
-```java
-@Autowired
-private NacosUtils nacosUtils;
-```
-
-##### 1.2.1 获取配置列表
-
-完整包路径：`com.meritdata.cloud.utils.NacosUtils`
-
-方法：`getConfigList(dataId)`
-
-入参：String dataId
-
-返回：Map
-
-使用场景：获取Nacos上某个配置分组的所有配置项
-
-示例：
-```java
-Map configMap = nacosUtils.getConfigList("common-cloud-system-manage.properties");
-```
-
-##### 1.2.2 获取配置文件
-
-方法：`getConfigFile(dataId)`
-
-入参：String dataId
-
-返回：String
-
-使用场景：获取Nacos上某个配置文件的完整内容
-
-示例：
-```java
-String content = nacosUtils.getConfigFile("application.properties");
-```
-
-##### 1.2.3 获取配置值
-
-方法：`getConfigValue(dataId, configKey)`
-
-入参：String dataId, String configKey
-
-返回：String
-
-使用场景：获取Nacos上指定配置项的值
-
-示例：
-```java
-String value = nacosUtils.getConfigValue("common-cloud-system-manage.properties", "meritdata.cloud.security-label-show");
-```
-
-##### 1.2.4 获取所有配置文件
-
-方法：`getAllConfigFile()`
-
-入参：无
-
-返回：Map<String, String>
-
-使用场景：获取Nacos上所有配置文件的键值对
-
-示例：
-```java
-Map<String, String> allConfigs = nacosUtils.getAllConfigFile();
-```
-
-##### 1.2.5 修改配置
-
-方法：`updateConfig(dataId, configKey, configValue)`
-
-入参：String dataId, String configKey, String configValue
-
-返回：boolean
-
-使用场景：修改Nacos上的配置值
-
-示例：
-```java
-boolean success = nacosUtils.updateConfig("common-cloud-system-manage.properties",
-    "meritdata.cloud.security-label-show", "true");
-```
-
-##### 1.2.6 更新配置文件
-
-方法：`updateConfigFile(dataId, quote)`
-
-入参：String dataId, String quote
-
-返回：boolean
-
-使用场景：更新整个配置文件内容
-
-示例：
-```java
-boolean success = nacosUtils.updateConfigFile("application.properties", newConfigContent);
-```
-
-##### 1.2.7 新增配置
-
-方法：`addConfig(dataId, configKey, configValue)`
-
-入参：String dataId, String configKey, String configValue
-
-返回：boolean
-
-使用场景：在Nacos上新增配置项
-
-示例：
-```java
-boolean added = nacosUtils.addConfig("custom.properties", "custom.key", "customValue");
-```
-
-##### 1.2.8 重置配置文件
-
-方法：`reSetConfigFile(dataId, quote)`
-
-入参：String dataId, String quote
-
-返回：boolean
-
-使用场景：重置配置文件内容
-
-示例：
-```java
-nacosUtils.reSetConfigFile("reset.properties", defaultContent);
-```
-
-##### 1.2.9 清除配置文件
-
-方法：`clearConfigFile(dataId)`
-
-入参：String dataId
-
-返回：boolean
-
-使用场景：清除Nacos上某个配置文件的所有内容
-
-示例：
-```java
-nacosUtils.clearConfigFile(dataId);
-```
-
-##### 1.2.10 获取Nacos Token
-
-方法：`getNacosToken()`
-
-入参：无
-
-返回：String
-
-使用场景：获取Nacos访问令牌
-
-示例：
-```java
-String token = nacosUtils.getNacosToken();
-```
-
----
-
-## 💡 使用建议
-- **`NacosUtils` 是 Spring Bean**：`@Autowired private NacosUtils nacosUtils;` 注入，**不要**用 `NacosUtils.xxx` 静态调用。
-- **配置 dataId 命名规范**：使用 `common-{模块}.properties`（如 `common-cloud-system-manage.properties`），保持与 bootstrap.properties 中声明的 profile 一致。
-- **运行时动态变更**：对于需要"不重启服务切换功能开关"的场景，可调用 `updateConfig` 后结合 `@RefreshScope` 实现热刷新。
-
-## 🔗 相关章节
-- 02_一基础设施-1.1缓存操作-SysCacheServiceFacade.md
+---
+name: 一基础设施-1.2配置中心-NacosUtils
+source-file: 公共资产清单
+source-section: 一、基础设施类 → 1.2 配置中心 → NacosUtils L518-L684
+keywords: [Nacos配置中心, NacosUtils, getConfigList, publishConfig, MeritdataCloudProperties, Spring Bean]
+use-cases: [动态读取Nacos配置, 修改Nacos配置, 配置文件批量更新, Nacos鉴权Token获取]
+related: [02_一基础设施-1.1缓存操作-SysCacheServiceFacade.md]
+---
+
+# 1.2 配置中心 — NacosUtils
+
+> **原文章节**：`公共资产清单 → 一、基础设施类 → 1.2 配置中心 → NacosUtils`
+> **行号范围**：L518-L684
+
+## 🎯 一句话
+`NacosUtils` 提供 Nacos 配置的读写能力，对外暴露 10 个方法（基于 Spring Bean 注入），常用于运行时动态获取/修改配置。
+
+## 📋 接口/方法清单
+
+### 1.2 配置中心
+
+#### NacosUtils
+
+**注意**：`NacosUtils` **不是静态工具类**，它是一个Spring Bean，需要通过依赖注入获取实例。类上有`@DisableEncrypt`注解，但方法使用`@Autowired`注入`MeritdataCloudProperties`和`Environment`。
+
+**正确用法**（通过Spring注入）：
+```java
+@Autowired
+private NacosUtils nacosUtils;
+```
+
+##### 1.2.1 获取配置列表
+
+完整包路径：`com.meritdata.cloud.utils.NacosUtils`
+
+方法：`getConfigList(dataId)`
+
+入参：String dataId
+
+返回：Map
+
+使用场景：获取Nacos上某个配置分组的所有配置项
+
+示例：
+```java
+Map configMap = nacosUtils.getConfigList("common-cloud-system-manage.properties");
+```
+
+##### 1.2.2 获取配置文件
+
+方法：`getConfigFile(dataId)`
+
+入参：String dataId
+
+返回：String
+
+使用场景：获取Nacos上某个配置文件的完整内容
+
+示例：
+```java
+String content = nacosUtils.getConfigFile("application.properties");
+```
+
+##### 1.2.3 获取配置值
+
+方法：`getConfigValue(dataId, configKey)`
+
+入参：String dataId, String configKey
+
+返回：String
+
+使用场景：获取Nacos上指定配置项的值
+
+示例：
+```java
+String value = nacosUtils.getConfigValue("common-cloud-system-manage.properties", "meritdata.cloud.security-label-show");
+```
+
+##### 1.2.4 获取所有配置文件
+
+方法：`getAllConfigFile()`
+
+入参：无
+
+返回：Map<String, String>
+
+使用场景：获取Nacos上所有配置文件的键值对
+
+示例：
+```java
+Map<String, String> allConfigs = nacosUtils.getAllConfigFile();
+```
+
+##### 1.2.5 修改配置
+
+方法：`updateConfig(dataId, configKey, configValue)`
+
+入参：String dataId, String configKey, String configValue
+
+返回：boolean
+
+使用场景：修改Nacos上的配置值
+
+示例：
+```java
+boolean success = nacosUtils.updateConfig("common-cloud-system-manage.properties",
+    "meritdata.cloud.security-label-show", "true");
+```
+
+##### 1.2.6 更新配置文件
+
+方法：`updateConfigFile(dataId, quote)`
+
+入参：String dataId, String quote
+
+返回：boolean
+
+使用场景：更新整个配置文件内容
+
+示例：
+```java
+boolean success = nacosUtils.updateConfigFile("application.properties", newConfigContent);
+```
+
+##### 1.2.7 新增配置
+
+方法：`addConfig(dataId, configKey, configValue)`
+
+入参：String dataId, String configKey, String configValue
+
+返回：boolean
+
+使用场景：在Nacos上新增配置项
+
+示例：
+```java
+boolean added = nacosUtils.addConfig("custom.properties", "custom.key", "customValue");
+```
+
+##### 1.2.8 重置配置文件
+
+方法：`reSetConfigFile(dataId, quote)`
+
+入参：String dataId, String quote
+
+返回：boolean
+
+使用场景：重置配置文件内容
+
+示例：
+```java
+nacosUtils.reSetConfigFile("reset.properties", defaultContent);
+```
+
+##### 1.2.9 清除配置文件
+
+方法：`clearConfigFile(dataId)`
+
+入参：String dataId
+
+返回：boolean
+
+使用场景：清除Nacos上某个配置文件的所有内容
+
+示例：
+```java
+nacosUtils.clearConfigFile(dataId);
+```
+
+##### 1.2.10 获取Nacos Token
+
+方法：`getNacosToken()`
+
+入参：无
+
+返回：String
+
+使用场景：获取Nacos访问令牌
+
+示例：
+```java
+String token = nacosUtils.getNacosToken();
+```
+
+---
+
+## 💡 使用建议
+- **`NacosUtils` 是 Spring Bean**：`@Autowired private NacosUtils nacosUtils;` 注入，**不要**用 `NacosUtils.xxx` 静态调用。
+- **配置 dataId 命名规范**：使用 `common-{模块}.properties`（如 `common-cloud-system-manage.properties`），保持与 bootstrap.properties 中声明的 profile 一致。
+- **运行时动态变更**：对于需要"不重启服务切换功能开关"的场景，可调用 `updateConfig` 后结合 `@RefreshScope` 实现热刷新。
+
+## 🔗 相关章节
+- 02_一基础设施-1.1缓存操作-SysCacheServiceFacade.md

package/skills/{meritdata-dev-docs-file-finder/references/dev-docs → 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

@@ -120,7 +120,7 @@ related: [17, 01]
 
 ## 💡 使用建议
 
-1. **版本锁定**：所有 `cloud-module-*` 依赖固定 `6.13.2`，与 `pom.xml` 中 `meritdata-cloud.version` 一致，避免序列化错误。
+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` 静态组件，不要自研。

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. 缓存键避免包含密码、令牌、身份证号或完整会话对象
+
+---