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

package/skills/meritdata-platform-config-item/references/nacos-config//346/224/273/347/225/245-11-/351/205/215/347/275/256/351/241/271-/347/253/240/350/212/20203_/351/205/215/347/275/256/351/241/271/347/232/204/344/275/277/347/224/250.md

@@ -0,0 +1,45 @@
+---
+name: 攻略-11-配置项-章节03_配置项的使用
+description: 配置项的使用 — 美林平台系统配置项管理（命名空间 + 9 个配置文件 + 全量配置项说明）
+keywords: [配置项, nacos, 命名空间, common.properties, datasource, cache, gateway, cas, bpm, 多租户, 配置项的使用]
+use-cases: [nacos 配置查询, 配置项修改, 新增配置, 配置项文件说明]
+source-section: 3. 配置项的使用
+source-file: 应用开发平台-基础平台-使用攻略（二）：系统配置项管理.md
+---
+
+# 3 配置项的使用
+
+## 📋 API 契约（机器可读）
+
+```json
+{
+  "apiName": "MeritdataCloudProperties",
+  "type": "class",
+  "signature": "class MeritdataCloudProperties",
+  "functionDesc": "配置实体类（@ConfigurationProperties 绑定）",
+  "module": "platform",
+  "classMethods": [],
+  "usagePattern": "通过 Spring 容器注入使用",
+  "bestPractice": "遵循 Spring Bean 生命周期，使用 @Autowired 注入"
+}
+```
+
+在配置中心中维护的配置项，引入到系统中有两种方式，一种是使用@Vaule 注解，一种是封装成配置实体类。
+
+### 3.1 @Value 注解使用
+
+```java
+@Value("\${spring.application.name}")
+private String applicationName;
+```
+
+通过以上方式使用时，需要在使用的类上添加<font color="red">@RefreshScope</font>注解，否则配置自动更新不能生效
+
+### 3.2 配置项实体类
+
+通过@ConfigurationProperties(prefix = "meritdata.cloud")
+可以将 meritdata.cloud.xxxx-xxxx-xxxx 为前缀的配置项封装为实体类属性，配置以’-’分隔，属性名以驼峰形式命名
+如 meritdata.cloud.xx-xx 转为实体属性后为 xxXx;
+
+在 config 文件中通过@EnableConfigurationProperties({MeritdataCloudProperties.class})进行引入
+[IMG: image]

package/skills/meritdata-platform-config-item/references/nacos-utils-api.md

@@ -0,0 +1,76 @@
+# NacosUtils 10 方法速查
+
+## 接口定义
+
+```java
+public class NacosUtils {
+    public static String getConfigValue(String dataId, String group);
+    public static List<ConfigInfo> getConfigList(String group);
+    public static boolean updateConfig(String dataId, String group, String content);
+    public static boolean addConfig(String dataId, String group, String content);
+    public static boolean deleteConfig(String dataId, String group);
+    public static boolean publishConfig(String dataId, String group, String content);
+    public static List<ConfigInfo> getConfigListByPrefix(String prefix);
+    public static String getConfigValue(String dataId, String group, long timeoutMs);
+    public static boolean watchConfig(String dataId, String group, ConfigWatcher watcher);
+    public static void stopWatch(String dataId, String group);
+}
+```
+
+## 10 方法速查
+
+| 方法 | 用途 |
+|------|------|
+| `getConfigValue` | 读单个配置 |
+| `getConfigValue (3参)` | 读配置（带超时） |
+| `getConfigList` | 读 group 下所有配置 |
+| `getConfigListByPrefix` | 按前缀查询 |
+| `addConfig` | 新增配置 |
+| `updateConfig` | 更新配置 |
+| `deleteConfig` | 删除配置 |
+| `publishConfig` | 发布配置 |
+| `watchConfig` | 监听配置变更 |
+| `stopWatch` | 停止监听 |
+
+## 典型用法
+
+### 动态读配置
+
+```java
+String value = NacosUtils.getConfigValue("common-${APP_NAME}.properties", "DEFAULT_GROUP");
+// 应用运行时配置变更 → 自动生效（需 @RefreshScope）
+```
+
+### 监听配置变更
+
+```java
+NacosUtils.watchConfig("common-business.properties", "DEFAULT_GROUP", new ConfigWatcher() {
+    public void receiveConfigInfo(String configInfo) {
+        // 收到变更通知
+        log.info("配置已更新: {}", configInfo);
+    }
+});
+```
+
+### 运行时动态改配置
+
+```java
+NacosUtils.updateConfig(
+    "common-business.properties",
+    "DEFAULT_GROUP",
+    "meritdata.cloud.yourapp.pool-size=30"
+);
+// 配合 @RefreshScope，依赖此配置的 Bean 自动刷新
+```
+
+## 配合 @ConfigurationProperties
+
+```java
+@Data
+@Configuration
+@ConfigurationProperties(prefix = "meritdata.cloud.yourapp")
+@RefreshScope  // 关键：Nacos 改了生效
+public class YourAppProperties {
+    private Integer poolSize;
+}
+```

package/skills/meritdata-platform-config-item/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/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: meritdata-platform-core
+description: MeritData 平台后端基础设施（缓存、Nacos 配置、SM2/SM3/SM4、审计日志、会话访问、数据密级过滤）。用于需要 NacosUtils、SessionUtils、SysCacheServiceFacade、Sm2Utils、EnableDataSecretFilter 等平台 API 的 MeritData 项目。
+metadata:
+  version: "1.0.0"
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-01"
+  risk: medium
+  allowed-tools: Read, Grep, Glob
+---
+
+## ⭐ MUST DO
+
+**先确认目标项目属于 MeritData 平台，仅使用已发布的 API 签名，禁止在生成代码时要求用户提供平台源码或反编译 Jar。**
+
+## 触发条件 / 不适用
+
+**适用**：
+- 使用 NacosUtils / SessionUtils / SysCacheServiceFacade / Sm2Utils
+- 配置 `EnableDataSecretFilter` 行级权限
+- 接入 `@LogOperation` 审计日志
+
+**不适用**：
+- 同 JVM 限定场景 → `meritdata-platform-entities`
+- 跨 JVM 业务服务的数据访问 → `.claude/rules/data-boundary-rules.md`
+
+## 主题路由
+
+| 任务 | 优先读取 |
+| --- | --- |
+| 缓存、队列、计数器、发布订阅、幂等 | [`references/cache.md`](references/cache.md) |
+| Nacos 读取或受控修改 | [`references/nacos.md`](references/nacos.md) |
+| SM2、SM3、SM4、密码解密 | [`references/crypto.md`](references/crypto.md) |
+| 操作日志、字段变更日志、`@LogOperation` | [`references/logging.md`](references/logging.md) |
+| 数据密级过滤与行级权限 | [`references/data-secret.md`](references/data-secret.md) |
+| 当前用户、租户、IP、在线用户 | [`references/session.md`](references/session.md) |
+
+## 工作方式（Step 1/2/3/4）
+
+### Step 1：兼容性检查
+
+- 检查目标项目的依赖、已有 import 和配置
+- 本 skill 不保证任意平台版本都提供同名 API
+
+### Step 2：安全边界
+
+- 不输出密钥、令牌、密码或默认加密的
+- 加密材料必须来自已批准的配置或密钥服务
+- Nacos 写入、踢出用户、缓存清理和密级特权访问均为高影响操作
+
+### Step 3：读取 reference
+
+按主题路由读取对应 md 文件。状态修改补最小验证：缓存过期或幂等、Nacos 回读、密级正反用例、会话操作审计。
+
+### Step 4：跨 skill 协作
+
+- 需要实体字段 → `meritdata-platform-entities`
+- 需要外部接口 → `meritdata-platform-integration`
+- 需要调度 → `meritdata-platform-job`
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 假定租户或密级 Filter 已启用 | 跨环境行为不一致 | 先在目标项目验证 |
+| 使用未发布 API | 平台升级后失效 | 仅使用随 Skill 发布的证据 |
+| 加密材料硬编码 | 安全风险 | 通过配置中心注入 |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 平台实体字段 → `meritdata-platform-entities`
+  - 平台开放接口 → `meritdata-platform-integration`
+  - 数据边界强制门禁 → `.claude/rules/data-boundary-rules.md`
+- **强制要求**：高影响操作（写 Nacos / 缓存清理 / 密级特权）前必须先确认环境、权限、范围和回滚方式

package/skills/meritdata-platform-core/agents/openai.yaml

@@ -0,0 +1,37 @@
+display_name: "MeritData 平台 Core"
+short_description: "MeritData 后端基础设施（缓存/Nacos/国密/日志/会话/密级）"
+default_prompt: |
+  meritdata-platform-core 处理 MeritData 平台后端基础设施场景。
+
+  适用场景：
+  - 缓存、队列、计数器、发布订阅（SysCacheServiceFacade）
+  - Nacos 配置读写（NacosUtils）
+  - 国密 SM2/SM3/SM4（Sm2Utils）
+  - 操作日志、字段变更日志（@LogOperation）
+  - 数据密级过滤（EnableDataSecretFilter）
+  - 当前用户、租户、IP、在线用户（SessionUtils）
+
+  使用方式：
+  ```
+  meritdata-platform-core <需求>
+  ```
+
+  工作方式：
+  1. 确认目标项目属于 MeritData 平台
+  2. 仅使用随 Skill 发布的 API 签名
+  3. 按主题路由读取 references/ 中的专题 md
+  4. 状态修改补最小验证：缓存过期或幂等、Nacos 回读、密级正反用例
+  5. 高影响操作前先确认环境、权限、范围和回滚方式
+
+  6 个 references：
+  - cache.md（缓存/队列/计数器/幂等）
+  - nacos.md（Nacos 读写）
+  - crypto.md（SM2/SM3/SM4）
+  - logging.md（@LogOperation）
+  - data-secret.md（数据密级过滤）
+  - session.md（当前用户/租户/IP）
+
+  强制约束：
+  - 不输出密钥、令牌、密码
+  - 不假定租户或密级 Filter 已启用
+  - 高影响操作必须有回滚方案