@alanwang-merit/meritdata-platform-skill-package 1.0.0

package/skills/meritdata-platform-nacos-config/references/configuration-properties.md

@@ -0,0 +1,295 @@
+# `@ConfigurationProperties` 配置项管理（configuration-properties）
+
+> **目的**：补齐 v2.4.0 复核发现的覆盖缺口——研发版 `meritdata-platform-config-item` 的 `MeritdataCloudProperties` 实体类 + `@ConfigurationProperties` 标准用法。
+> **场景**：业务可配置参数（连接池 / 超时 / 业务开关）+ `@RefreshScope` 热更新。
+> **来源**：研发版 `meritdata-platform-config-item` v1.0.0 + 攻略-11。
+
+---
+
+## 一、MeritdataCloudProperties 模式
+
+### 1.1 平台实体类（应用配置根）
+
+平台约定所有二开业务配置**必须挂在 `meritdata.cloud.*` 前缀下**：
+
+```java
+@Data
+@Configuration
+@ConfigurationProperties(prefix = "meritdata.cloud")
+public class MeritdataCloudProperties {
+
+    /**
+     * 二开业务通用配置子节点
+     */
+    private YourApp yourApp = new YourApp();
+
+    @Data
+    public static class YourApp {
+        private Integer poolSize = 10;        // 连接池大小
+        private Long timeoutMs = 3000L;        // 超时（毫秒）
+        private Boolean enabled = true;        // 业务开关
+        private String bizPrefix = "";         // 业务前缀
+    }
+}
+```
+
+### 1.2 Nacos 配置（Nacos 控制台）
+
+```
+data-id: common-${APP_NAME}.properties
+group: DEFAULT_GROUP
+
+# 内容
+meritdata.cloud.your-app.pool-size=20
+meritdata.cloud.your-app.timeout-ms=5000
+meritdata.cloud.your-app.enabled=true
+meritdata.cloud.your-app.biz-prefix=pur_
+```
+
+### 1.3 启用配置类
+
+```java
+@SpringBootApplication
+@EnableConfigurationProperties(MeritdataCloudProperties.class)
+public class YourApplication { ... }
+```
+
+---
+
+## 二、3 步标准用法（MUST）
+
+### Step 1：定义配置类
+
+```java
+@Data
+@Configuration
+@ConfigurationProperties(prefix = "meritdata.cloud.yourapp")
+public class YourAppProperties {
+    private Integer poolSize = 10;
+    private Long timeoutMs = 3000L;
+    private Boolean enabled = true;
+}
+```
+
+### Step 2：Nacos 配置
+
+```properties
+meritdata.cloud.yourapp.pool-size=20
+meritdata.cloud.yourapp.timeout-ms=5000
+meritdata.cloud.yourapp.enabled=true
+```
+
+### Step 3：注入使用（带 `@RefreshScope`）
+
+```java
+@Service
+@RefreshScope  // Nacos 变更自动刷新
+public class YourService {
+    @Autowired private YourAppProperties props;
+
+    public void doIt() {
+        if (props.getEnabled()) {
+            // ...
+        }
+    }
+}
+```
+
+---
+
+## 三、与 `@Value` / `@NacosValue` 的区别
+
+| 维度 | `@Value` | `@ConfigurationProperties` | `@NacosValue` |
+|------|----------|----------------------------|---------------|
+| **配置源** | application.yml | application.yml / Nacos | 仅 Nacos |
+| **批量绑定** | ❌ 单个字段 | ✅ POJO 全字段 | ❌ 单个字段 |
+| **类型安全** | ⚠️ SpEL 表达式 | ✅ 强类型 | ⚠️ SpEL |
+| **热更新** | ❌ | ✅（@RefreshScope）| ✅（自动监听）|
+| **校验** | ❌ | ✅（@Validated）| ❌ |
+| **典型场景** | 简单单值 | 业务配置组 | Nacos 专项值 |
+
+**推荐**：
+- 业务配置（连接池/超时/开关）→ `@ConfigurationProperties` + `@RefreshScope`
+- Nacos 简单动态值 → `@NacosValue`
+- application.yml 单值 → `@Value`
+
+---
+
+## 四、高级用法
+
+### 4.1 配置校验（`@Validated`）
+
+```java
+@Data
+@Configuration
+@ConfigurationProperties(prefix = "meritdata.cloud.yourapp")
+@Validated
+public class YourAppProperties {
+
+    @Min(value = 1, message = "pool-size 必须 ≥ 1")
+    private Integer poolSize = 10;
+
+    @NotNull
+    @Min(value = 100, message = "timeout-ms 必须 ≥ 100")
+    private Long timeoutMs = 3000L;
+
+    @Pattern(regexp = "^[a-z_]+$", message = "biz-prefix 必须小写蛇形")
+    private String bizPrefix = "";
+}
+```
+
+启动时若校验失败，**应用启动直接报错**（fail-fast）：
+
+```
+***************************
+APPLICATION FAILED TO START
+***************************
+Description:
+Binding to target com.example.YourAppProperties@xxx failed:
+
+    Reason: pool-size 必须 ≥ 1
+    Value: 0
+```
+
+### 4.2 嵌套配置（List / Map）
+
+```java
+@Data
+@Configuration
+@ConfigurationProperties(prefix = "meritdata.cloud.yourapp")
+public class YourAppProperties {
+
+    /** 业务白名单列表 */
+    private List<String> whitelist = new ArrayList<>();
+
+    /** 多数据源映射 */
+    private Map<String, DataSourceConfig> dataSources = new HashMap<>();
+
+    @Data
+    public static class DataSourceConfig {
+        private String url;
+        private String username;
+        private String password;
+    }
+}
+```
+
+```properties
+# Nacos 配置
+meritdata.cloud.yourapp.whitelist[0]=user1
+meritdata.cloud.yourapp.whitelist[1]=user2
+
+meritdata.cloud.yourapp.dataSources.master.url=jdbc:mysql://...
+meritdata.cloud.yourapp.dataSources.master.username=root
+```
+
+### 4.3 监听 Nacos 变更
+
+```java
+@Component
+public class YourAppPropertiesListener {
+
+    @Autowired
+    private YourAppProperties props;
+
+    @NacosConfigListener(dataId = "common-yourapp.properties")
+    public void onConfigChange(String newConfig) {
+        log.info("Nacos 配置变更: {}", newConfig);
+        // 配置变更后的额外逻辑（如清缓存）
+    }
+}
+```
+
+---
+
+## 五、典型场景
+
+### 5.1 数据库连接池配置
+
+```java
+@Data
+@Configuration
+@ConfigurationProperties(prefix = "meritdata.cloud.datasource")
+public class DataSourceProperties {
+    private Integer poolSize = 20;
+    private Long connectionTimeoutMs = 30000L;
+    private Long idleTimeoutMs = 600000L;
+}
+```
+
+```properties
+meritdata.cloud.datasource.pool-size=50
+meritdata.cloud.datasource.connection-timeout-ms=10000
+```
+
+### 5.2 业务开关（feature flag）
+
+```java
+@Data
+@Configuration
+@ConfigurationProperties(prefix = "meritdata.cloud.feature")
+public class FeatureProperties {
+    private Boolean enableNewApproval = false;     // 新审批流开关
+    private Boolean enableAsyncExport = true;      // 异步导出开关
+    private String  apiRateLimit = "1000";         // API 限流 QPS
+}
+```
+
+```java
+@Service
+@RefreshScope
+public class ApprovalService {
+    @Autowired private FeatureProperties feature;
+
+    public void submit() {
+        if (feature.getEnableNewApproval()) {
+            // 新审批流
+        } else {
+            // 旧审批流
+        }
+    }
+}
+```
+
+### 5.3 超时配置
+
+```java
+@Data
+@Configuration
+@ConfigurationProperties(prefix = "meritdata.cloud.httpclient")
+public class HttpClientProperties {
+    private Long connectTimeoutMs = 3000L;
+    private Long readTimeoutMs = 10000L;
+    private Integer retryCount = 3;
+}
+```
+
+---
+
+## 六、与其他 skill 的协作
+
+| 场景 | 协作 skill |
+|------|----------|
+| NacosUtils 10 方法（动态读写配置）| `meritdata-platform-nacos-config/references/guide.md` |
+| Nacos 灰度发布流程 | `meritdata-nacos-importer/references/gray-publish.md` |
+| 敏感配置加密（数据库密码）| `meritdata-platform-nacos-config/references/encryption.md` |
+| 攻略-11 配置项使用 | `meritdata-platform-nacos-config/references/config-item-攻略/INDEX.md` |
+
+---
+
+## 七、常见错误
+
+| 错误 | 后果 | 正确做法 |
+|------|------|---------|
+| 用 `@Value` 单个注入 | 无法统一管理 | `@ConfigurationProperties` |
+| 不加 `@RefreshScope` | Nacos 改了不生效 | 加 `@RefreshScope` |
+| `@RefreshScope` 用 static | 不刷新 | 成员变量 |
+| 配置项 snake_case 跟 camelCase 混 | 反序列化报错 | 统一 camelCase |
+| 不做 `@Validated` | 启动时配置错误不暴露 | 加 `@Validated` + `@Min`/`@NotNull` |
+| 配置变更后不清缓存 | 旧缓存继续生效 | 监听 `onConfigChange` 清缓存 |
+
+---
+
+**最后更新**：2026-09-08（v2.4.0 P1 补齐）
+**来源**：研发版 `meritdata-platform-config-item` v1.0.0 + 攻略-11
+**整合位置**：`meritdata-platform-nacos-config/references/configuration-properties.md`

package/skills/meritdata-platform-nacos-config/references/dynamic-refresh.md

@@ -0,0 +1,156 @@
+# Nacos 动态刷新（nacos-config）
+
+> 配置变更后业务代码自动感知，无需重启。
+
+---
+
+## 1. 三种刷新粒度
+
+| 粒度 | 实现 | 适用场景 |
+|------|------|---------|
+| **方法级** | `@NacosValue(autoRefreshed = true)` | 单个配置项 |
+| **类级** | `@NacosConfigurationProperties` | 一组相关配置 |
+| **手动** | `NacosConfigService.getConfig()` | 运行时动态查 |
+
+## 2. @NacosValue 自动刷新
+
+```java
+@RestController
+public class FeatureController {
+
+    @NacosValue(value = "${feature.dark-mode:false}", autoRefreshed = true)
+    private boolean darkMode;
+
+    @NacosValue(value = "${feature.max-items:20}", autoRefreshed = true)
+    private int maxItems;
+}
+```
+
+Nacos 配置变更 → 自动推送 → 业务字段更新。
+
+## 3. @NacosConfigurationProperties 推荐方式
+
+```java
+@NacosConfigurationProperties(dataId = "your-2nd-service.yaml", autoRefreshed = true)
+@Data
+public class AppConfig {
+
+    /** 订单超时（秒）*/
+    private int orderTimeout = 30;
+
+    /** 是否启用短信通知 */
+    private boolean smsEnabled = false;
+
+    /** 外部 API 地址 */
+    private String apiUrl;
+
+    /** 允许跨域来源 */
+    private List<String> allowedOrigins;
+}
+```
+
+使用：
+
+```java
+@Service
+public class OrderService {
+
+    @Autowired
+    private AppConfig config;
+
+    public void doSomething() {
+        if (config.isSmsEnabled()) {
+            smsClient.send(...);
+        }
+    }
+}
+```
+
+## 4. 自定义刷新监听
+
+### 4.1 场景
+
+配置变更后需要触发自定义逻辑（如重建缓存）。
+
+### 4.2 实现
+
+```java
+@Component
+public class ConfigRefreshListener implements NacosConfigListener {
+
+    @Override
+    public void onReceived(String dataId, String group, String configInfo) {
+        log.info("配置变更: dataId={}, group={}, info={}", dataId, group, configInfo);
+        // 重建缓存
+        cacheManager.clearAll();
+        // 重新初始化
+        service.init();
+    }
+}
+```
+
+注册监听：
+
+```java
+configService.addListener("your-2nd-service.yaml", "DEFAULT_GROUP", listener);
+```
+
+## 5. ❌ 反模式
+
+### 5.1 ❌ 注解不写 autoRefreshed
+
+```java
+// ❌ 错：配置变更后字段不更新
+@NacosValue(value = "${feature.dark-mode:false}")
+private boolean darkMode;
+
+// ✅ 正确
+@NacosValue(value = "${feature.dark-mode:false}", autoRefreshed = true)
+private boolean darkMode;
+```
+
+### 5.2 ❌ 刷新粒度过细导致性能问题
+
+```java
+// ❌ 错：100 个配置项都加 @NacosValue → 100 个监听器
+@NacosValue(value = "${feature.a}", autoRefreshed = true)
+private String a;
+@NacosValue(value = "${feature.b}", autoRefreshed = true)
+private String b;
+// ... 98 个
+
+// ✅ 正确：相关配置聚合到 @NacosConfigurationProperties
+@NacosConfigurationProperties(dataId = "feature.yaml", autoRefreshed = true)
+public class FeatureConfig {
+    private String a;
+    private String b;
+    // ...
+}
+```
+
+### 5.3 ❌ 刷新失败不处理
+
+```java
+// ❌ 错：自定义刷新逻辑抛出异常 → 配置变更失效
+@Override
+public void onReceived(String dataId, String group, String configInfo) {
+    cacheManager.clearAll();  // 抛出异常
+}
+
+// ✅ 正确：try-catch + 日志
+@Override
+public void onReceived(String dataId, String group, String configInfo) {
+    try {
+        cacheManager.clearAll();
+    } catch (Exception e) {
+        log.error("刷新缓存失败", e);
+    }
+}
+```
+
+## 6. 关联阅读
+
+- [guide.md](guide.md) — Nacos 配置基础
+- [env-and-gray.md](env-and-gray.md) — 多环境隔离
+- [encryption.md](encryption.md) — 敏感配置加密
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-nacos-config/references/encryption.md

@@ -0,0 +1,182 @@
+# Nacos 敏感配置加密（nacos-config）
+
+> 数据库密码、API Key、密钥等敏感配置**禁止明文**存 Nacos。
+
+---
+
+## 1. 加密方式
+
+### 1.1 平台支持的方案
+
+| 方案 | 适用 | 配置位置 |
+|------|------|---------|
+| **Nacos 加密插件** | 简单 AES 加密 | Nacos 控制台 |
+| **KMS 集成** | 高安全场景 | 外部 KMS |
+| **Jasypt** | 配置文件加密 | application.yml |
+| **Vault** | 多产品通用 | HashiCorp Vault |
+
+## 2. Nacos 加密插件（推荐）
+
+### 2.1 加密配置项
+
+在 Nacos 控制台编辑配置时，对敏感字段使用加密：
+
+```yaml
+# 原始（明文）
+spring:
+  datasource:
+    password: mySecretPassword123
+
+# 加密后（Nacos 自动用 ENC() 包裹）
+spring:
+  datasource:
+    password: ENC(AES 加密后的密文)
+```
+
+### 2.2 客户端解密
+
+```xml
+<dependency>
+    <groupId>com.alibaba.nacos</groupId>
+    <artifactId>nacos-spring-boot-starter</artifactId>
+</dependency>
+```
+
+平台默认启用解密，业务代码**无感知**。
+
+## 3. KMS 集成（高安全）
+
+### 3.1 场景
+
+金融、医疗场景需要 FIPS-140 级别合规，使用外部 KMS。
+
+### 3.2 配置
+
+```yaml
+spring:
+  cloud:
+    nacos:
+      config:
+        # 配置项值引用 KMS
+        extension-configs[0]:
+          data-id: kms-ref.yaml
+          refresh: true
+```
+
+```yaml
+# kms-ref.yaml（Nacos 配置）
+spring:
+  datasource:
+    password: KMS_REF(database-prod-password)  # 平台启动时从 KMS 取值
+```
+
+### 3.3 业务代码无感知
+
+```java
+@NacosValue(value = "${spring.datasource.password}")
+private String dbPassword;  // 启动时已被 KMS 解析为明文
+```
+
+## 4. Jasypt（配置文件加密）
+
+### 4.1 引入依赖
+
+```xml
+<dependency>
+    <groupId>com.github.ulisesbocchio</groupId>
+    <artifactId>jasypt-spring-boot-starter</artifactId>
+    <version>3.0.5</version>
+</dependency>
+```
+
+### 4.2 配置加密
+
+```bash
+# 用 jasypt 加密密码
+java -cp jasypt-1.9.3.jar \
+  org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI \
+  algorithm=PBEWithMD5AndDES \
+  input=mySecretPassword123 \
+  password=MY_MASTER_PASSWORD
+
+# 输出：ENC(xxxxxx)
+```
+
+### 4.3 在 Nacos 中使用
+
+```yaml
+spring:
+  datasource:
+    password: ENC(xxxxxx)  # 启动时自动解密
+```
+
+### 4.4 主密码传递
+
+```yaml
+# ❌ 错：主密码写在配置里
+jasypt:
+  encryptor:
+    password: MY_MASTER_PASSWORD
+
+# ✅ 正确：主密码通过环境变量
+jasypt:
+  encryptor:
+    password: ${JASYPT_MASTER_PASSWORD}
+```
+
+启动：
+
+```bash
+JASYPT_MASTER_PASSWORD=xxx java -jar app.jar
+```
+
+## 5. ❌ 反模式
+
+### 5.1 ❌ 明文密码存 Nacos
+
+```yaml
+# ❌ 错：明文密码
+spring:
+  datasource:
+    password: mySecretPassword123
+```
+
+✅ 加密后存储。
+
+### 5.2 ❌ 密钥和加密数据放一起
+
+```yaml
+# ❌ 错：加密的密码 + 解密密钥都在 Nacos
+jasypt:
+  encryptor:
+    password: MY_MASTER_PASSWORD  # 密钥不能和数据放一起
+spring:
+  datasource:
+    password: ENC(xxxxxx)
+```
+
+✅ 主密码从 KMS 或环境变量。
+
+### 5.3 ❌ 加密但不解密
+
+```java
+// ❌ 错：业务代码用了加密字符串
+String password = config.getPassword();  // "ENC(xxxxxx)"
+dataSource.setPassword(password);  // JDBC 连不上
+```
+
+✅ 确保平台已配置解密。
+
+## 6. 审计与合规
+
+- [ ] 所有敏感配置已加密（Nacos 扫描）
+- [ ] 主密钥从外部 KMS 读取
+- [ ] 密钥定期轮换（建议 90 天）
+- [ ] 解密操作有审计日志
+
+## 7. 关联阅读
+
+- [guide.md](guide.md) — Nacos 配置基础
+- [dynamic-refresh.md](dynamic-refresh.md) — 动态刷新
+- [env-and-gray.md](env-and-gray.md) — 多环境隔离
+- [SKILL.md](../SKILL.md)