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

package/skills/meritdata-platform-platform-config/references/cache-and-persist.md

@@ -0,0 +1,234 @@
+# 配置缓存与持久化（platform-config）
+
+> 配置多级缓存策略 / 持久化 / 失效广播。
+
+---
+
+## 1. 缓存架构
+
+```
+请求 → getValue(code)
+   ↓
+L1: 本地（Caffeine，1 分钟）
+   ↓ miss
+L2: Redis（5 分钟）
+   ↓ miss
+L3: DB
+```
+
+## 2. 缓存 Key
+
+```
+config:meta:{code}              配置元数据
+config:value:SYSTEM:{code}      系统配置值
+config:value:TENANT:{tenantId}:{code}
+config:value:USER:{userId}:{code}
+config:audit:{code}:latest      最新审计
+```
+
+## 3. 缓存策略
+
+### 3.1 本地缓存
+
+```yaml
+config:
+  cache:
+    local:
+      enabled: true
+      expire-after-write: 1m
+      maximum-size: 5000
+```
+
+### 3.2 Redis 缓存
+
+```yaml
+config:
+  cache:
+    redis:
+      ttl: 5m
+      jitter: 1m         # 防止雪崩
+```
+
+### 3.3 预热
+
+```java
+@Component
+public class ConfigWarmup implements ApplicationRunner {
+    @Override
+    public void run(ApplicationArguments args) {
+        // 预热系统级配置
+        for (ConfigMeta meta : configMetaRepository.findByScope("SYSTEM")) {
+            configService.getString(meta.getCode());  // 加载到缓存
+        }
+    }
+}
+```
+
+## 4. 失效广播
+
+### 4.1 Redis Pub/Sub
+
+```
+configService.set(code, newValue)
+   ↓
+1. 写 DB
+   ↓
+2. 发事件 ConfigChangedEvent
+   ↓
+3. Redis publish "config:changed:{code}"
+   ↓
+4. 所有实例订阅 → 清本地缓存
+   ↓
+5. 业务订阅（如需）
+```
+
+### 4.2 实现
+
+```java
+@Component
+public class ConfigChangeBroadcaster {
+
+    @Autowired
+    private StringRedisTemplate redisTemplate;
+
+    public void broadcast(ConfigChangedEvent event) {
+        String channel = "config:changed:" + event.getCode();
+        redisTemplate.convertAndSend(channel, JSON.toJSONString(event));
+    }
+}
+
+@Component
+public class ConfigChangeListener implements MessageListener {
+    @Override
+    public void onMessage(Message message, byte[] pattern) {
+        String body = new String(message.getBody());
+        ConfigChangedEvent event = JSON.parseObject(body, ConfigChangedEvent.class);
+        cacheManager.evict("config:value:" + event.getScope() + ":" + event.getScopeId() + ":" + event.getCode());
+    }
+}
+```
+
+## 5. 持久化策略
+
+### 5.1 写流程
+
+```
+configService.set(code, value)
+   ↓
+1. 校验（类型、范围）
+   ↓
+2. 写 DB（t_config_value）
+   ↓
+3. 写审计（t_config_audit）
+   ↓
+4. 清 Redis
+   ↓
+5. 发广播
+```
+
+### 5.2 事务保证
+
+```java
+@Transactional
+public void set(String code, String value) {
+    // 1. 写值
+    configValueRepository.save(...);
+    // 2. 写审计
+    configAuditRepository.save(...);
+    // 事务保证值和审计同时成功或失败
+}
+```
+
+### 5.3 失败回滚
+
+```java
+try {
+    configService.set(code, value);
+} catch (Exception e) {
+    log.error("配置写入失败", e);
+    // 事务自动回滚
+    throw new BizException("配置修改失败");
+}
+```
+
+## 6. 特殊场景
+
+### 6.1 配置导入
+
+```java
+@PostMapping("/admin/configs/import")
+public Result importConfigs(@RequestParam("file") MultipartFile file) {
+    List<ConfigDTO> configs = parseFile(file);
+    for (ConfigDTO c : configs) {
+        configService.set(c.getCode(), c.getValue(), c.getScope(), c.getScopeId());
+    }
+    return Result.success();
+}
+```
+
+### 6.2 配置导出
+
+```java
+@GetMapping("/admin/configs/export")
+public void export(HttpServletResponse response) {
+    List<ConfigValue> values = configValueRepository.findAll();
+    EasyExcel.write(response.getOutputStream(), ConfigValue.class).doWrite(values);
+}
+```
+
+### 6.3 配置对比
+
+```java
+@GetMapping("/admin/configs/compare")
+public List<ConfigDiff> compare(@RequestParam String tenantA, @RequestParam String tenantB) {
+    return configService.compare(tenantA, tenantB);
+}
+```
+
+## 7. 监控指标
+
+```
+config_cache_hit_ratio         缓存命中率
+config_get_duration_ms         配置读取耗时
+config_set_total               配置写入次数
+config_set_failed_total        配置写入失败次数
+config_broadcast_total         广播次数
+```
+
+## 8. ❌ 反模式
+
+### 8.1 ❌ 配置无缓存
+
+```java
+// ❌ 错
+public String get(String code) {
+    return configRepository.find(code).getValue();  // 每次查 DB
+}
+```
+
+✅ 加缓存。
+
+### 8.2 ❌ 缓存不失效
+
+```java
+// ❌ 错：配置改了缓存不知道
+configRepository.save(config);  // 缓存值还是旧的
+```
+
+✅ 发广播 → 清缓存。
+
+### 8.3 ❌ 写入无事务
+
+```java
+// ❌ 错
+configValueRepository.save(value);
+configAuditRepository.save(audit);  // 失败回滚不到
+```
+
+✅ @Transactional 包裹。
+
+## 9. 关联阅读
+
+- [guide.md](guide.md) — 平台配置基础
+- [multi-tenant-and-audit.md](multi-tenant-and-audit.md) — 多租户 + 审计
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-platform-config/references/guide.md

@@ -0,0 +1,225 @@
+# 平台配置基础指南（platform-config）
+
+> 业务参数 / 系统参数 / 多租户配置 / 热更新 / 审计。
+
+---
+
+## 1. 配置类型
+
+| 类型 | 用途 | 例子 |
+|------|------|------|
+| **系统参数** | 全局生效 | 默认密码策略、Token 有效期 |
+| **业务参数** | 业务级 | 订单金额阈值、审批人白名单 |
+| **租户参数** | 租户级 | 不同租户不同规则 |
+
+## 2. 配置模型
+
+```
+ConfigGroup (配置组)
+├── code            -- 组编码
+├── name            -- 组名
+├── description
+└── configs: [Config]
+
+Config (配置项)
+├── code            -- 配置编码（如 "order.approve.threshold"）
+├── name            -- 显示名
+├── value           -- 值
+├── defaultValue
+├── type            -- STRING / NUMBER / BOOLEAN / JSON / LIST
+├── description
+├── readonly        -- 是否只读
+├── scope           -- SYSTEM / TENANT / USER
+└── validator       -- 校验规则
+```
+
+## 3. 配置接口
+
+### 3.1 读配置
+
+```java
+@Resource
+private IPlatformConfigService configService;
+
+// 全局配置
+String orderThreshold = configService.getString("order.approve.threshold");
+
+// 租户配置（多租户系统）
+String tenantThreshold = configService.getString("order.approve.threshold", tenantId);
+
+// 带默认值
+int timeout = configService.getInt("order.timeout", 30);
+
+// 类型化配置
+ConfigValue<OrderConfig> config = configService.getObject("order.config", OrderConfig.class);
+```
+
+### 3.2 @NacosValue 同步注解（推荐）
+
+```java
+@Service
+public class OrderService {
+
+    @NacosValue(value = "${order.approve.threshold:10000}", autoRefreshed = true)
+    private int approveThreshold;
+
+    public void approve(Order order) {
+        if (order.getAmount() > approveThreshold) {
+            // 高级别审批
+        }
+    }
+}
+```
+
+### 3.3 写配置
+
+```java
+@PostMapping("/admin/configs")
+public Result setConfig(@RequestBody ConfigDTO dto) {
+    configService.set(dto.getCode(), dto.getValue(), dto.getScope());
+    return Result.success();
+}
+```
+
+## 4. 多租户配置
+
+### 4.1 优先级
+
+```
+USER 级别配置  >  TENANT 级别配置  >  SYSTEM 级别配置  >  defaultValue
+```
+
+### 4.2 用法
+
+```java
+// 按租户查配置
+String tenantValue = configService.getString("order.threshold", tenantId);
+
+// 系统级（无 tenant 参数）
+String sysValue = configService.getString("order.threshold");
+```
+
+### 4.3 Fallback
+
+```java
+public String getValue(String code, String tenantId) {
+    // 1. 查租户配置
+    String tenantValue = tenantConfigRepository.find(code, tenantId);
+    if (tenantValue != null) return tenantValue;
+
+    // 2. 查系统配置
+    String sysValue = systemConfigRepository.find(code);
+    if (sysValue != null) return sysValue;
+
+    // 3. 默认值
+    return configMeta.getDefaultValue(code);
+}
+```
+
+## 5. 配置热更新
+
+详见 [nacos-config dynamic-refresh](../meritdata-platform-nacos-config/references/dynamic-refresh.md)。
+
+```yaml
+config:
+  hot-reload: true
+  notify-channels:
+    - redis-pubsub        # 跨实例广播
+    - websocket           # 推送给前端
+```
+
+## 6. 配置审计
+
+### 6.1 变更日志
+
+```sql
+CREATE TABLE t_config_audit (
+    id BIGINT PRIMARY KEY,
+    config_code VARCHAR(100),
+    old_value TEXT,
+    new_value TEXT,
+    operator_id VARCHAR(50),
+    operator_name VARCHAR(100),
+    change_type VARCHAR(20),       -- CREATE / UPDATE / DELETE
+    create_time DATETIME,
+    INDEX idx_code (config_code),
+    INDEX idx_time (create_time)
+);
+```
+
+### 6.2 审计写入
+
+```java
+@EventListener
+public void onConfigChanged(ConfigChangedEvent event) {
+    ConfigAudit audit = new ConfigAudit();
+    audit.setConfigCode(event.getCode());
+    audit.setOldValue(event.getOldValue());
+    audit.setNewValue(event.getNewValue());
+    audit.setOperatorId(SecurityUtils.getCurrentUserId());
+    audit.setChangeType(event.getChangeType());
+    auditRepository.save(audit);
+}
+```
+
+## 7. 配置校验
+
+```java
+public class ConfigValidator {
+    public void validate(ConfigDTO config) {
+        switch (config.getType()) {
+            case NUMBER:
+                double v = Double.parseDouble(config.getValue());
+                if (v < config.getMin() || v > config.getMax()) {
+                    throw new BizException("值超出范围");
+                }
+                break;
+            case JSON:
+                // 校验 JSON 格式
+                JSON.parse(config.getValue());
+                break;
+            case LIST:
+                String[] items = config.getValue().split(",");
+                if (items.length > config.getMaxItems()) {
+                    throw new BizException("超过最大项数");
+                }
+                break;
+        }
+    }
+}
+```
+
+## 8. ❌ 反模式
+
+### 8.1 ❌ 配置写在代码里
+
+```java
+// ❌ 错
+private static final int APPROVE_THRESHOLD = 10000;  // 改个值要重新部署
+```
+
+✅ 用配置中心。
+
+### 8.2 ❌ 配置变更无审计
+
+```java
+// ❌ 错：直接修改配置
+configRepository.save(config);  // 没记录谁改的
+```
+
+✅ 加审计日志。
+
+### 8.3 ❌ 租户配置串了
+
+```java
+// ❌ 错
+configService.set("order.threshold", "10000", Scope.SYSTEM);  // 改了租户 A 的值
+```
+
+✅ 显式区分 scope。
+
+## 9. 关联阅读
+
+- [multi-tenant-and-audit.md](multi-tenant-and-audit.md) — 多租户 + 审计
+- [cache-and-persist.md](cache-and-persist.md) — 缓存策略
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-platform-config/references/multi-tenant-and-audit.md

@@ -0,0 +1,254 @@
+# 多租户配置与审计（platform-config）
+
+> 多租户差异化配置 / 配置变更审计 / 灰度发布。
+
+---
+
+## 1. 多租户配置模型
+
+### 1.1 配置作用域
+
+| Scope | 适用 | 优先级 |
+|-------|------|--------|
+| SYSTEM | 全局生效 | 最低 |
+| TENANT | 单租户 | 中 |
+| USER | 单用户 | 最高 |
+
+### 1.2 数据表设计
+
+```sql
+-- 配置元数据
+CREATE TABLE t_config_meta (
+    code VARCHAR(100) PRIMARY KEY,
+    name VARCHAR(100),
+    type VARCHAR(20),          -- STRING/NUMBER/BOOLEAN/JSON
+    default_value TEXT,
+    min_value DOUBLE,
+    max_value DOUBLE,
+    description TEXT,
+    scope VARCHAR(20)          -- SYSTEM/TENANT/USER
+);
+
+-- 配置值（按 scope 分行）
+CREATE TABLE t_config_value (
+    id BIGINT PRIMARY KEY,
+    config_code VARCHAR(100),
+    scope VARCHAR(20),
+    scope_id VARCHAR(100),      -- tenant_id / user_id / null
+    value TEXT,
+    version INT,
+    create_time DATETIME,
+    update_time DATETIME,
+    UNIQUE KEY uk_code_scope (config_code, scope, scope_id)
+);
+```
+
+## 2. 租户配置管理
+
+### 2.1 给租户设置配置
+
+```java
+@PostMapping("/admin/tenants/{tenantId}/configs")
+public Result setTenantConfig(@PathVariable String tenantId, @RequestBody ConfigSetRequest req) {
+    configService.setForTenant(req.getCode(), req.getValue(), tenantId);
+    return Result.success();
+}
+```
+
+### 2.2 查询租户配置
+
+```java
+@GetMapping("/admin/tenants/{tenantId}/configs")
+public List<ConfigVO> tenantConfigs(@PathVariable String tenantId) {
+    return configService.listByTenant(tenantId);
+}
+```
+
+返回：
+
+```json
+[
+  {
+    "code": "order.threshold",
+    "name": "订单审批阈值",
+    "systemDefault": 10000,
+    "tenantValue": 50000,
+    "effectiveValue": 50000,
+    "source": "TENANT"
+  }
+]
+```
+
+### 2.3 继承与覆盖
+
+```java
+public String getEffectiveValue(String code, String tenantId) {
+    // 1. TENANT
+    String tenant = tenantConfigRepository.find(code, tenantId);
+    if (tenant != null) return tenant;
+
+    // 2. SYSTEM
+    String system = systemConfigRepository.find(code);
+    if (system != null) return system;
+
+    // 3. 默认
+    return configMetaRepository.findDefault(code);
+}
+```
+
+## 3. 配置审计
+
+### 3.1 审计日志
+
+```sql
+CREATE TABLE t_config_audit (
+    id BIGINT PRIMARY KEY,
+    config_code VARCHAR(100),
+    scope VARCHAR(20),
+    scope_id VARCHAR(100),
+    old_value TEXT,
+    new_value TEXT,
+    change_type VARCHAR(20),
+    operator_id VARCHAR(50),
+    operator_name VARCHAR(100),
+    client_ip VARCHAR(50),
+    create_time DATETIME,
+    INDEX idx_code_time (config_code, create_time),
+    INDEX idx_operator (operator_id)
+);
+```
+
+### 3.2 写入
+
+```java
+@EventListener
+public void onConfigChanged(ConfigChangedEvent event) {
+    ConfigAudit audit = new ConfigAudit();
+    audit.setConfigCode(event.getCode());
+    audit.setOldValue(event.getOldValue());
+    audit.setNewValue(event.getNewValue());
+    audit.setChangeType(event.getChangeType());
+
+    UserDTO user = SecurityUtils.getCurrentUser();
+    audit.setOperatorId(user.getUserId());
+    audit.setOperatorName(user.getRealName());
+    audit.setClientIp(SecurityUtils.getCurrentIp());
+
+    configAuditRepository.save(audit);
+}
+```
+
+### 3.3 审计查询
+
+```java
+@GetMapping("/admin/config-audits")
+public PageResult<ConfigAudit> query(ConfigAuditQuery query) {
+    return configAuditService.query(query);
+}
+```
+
+按配置项 / 时间范围 / 操作人筛选。
+
+### 3.4 敏感配置额外保护
+
+```yaml
+config:
+  sensitive-codes:
+    - "*.password"
+    - "*.secret"
+    - "*.key"
+```
+
+敏感配置的审计**必须**加密存储 `old_value` / `new_value`。
+
+## 4. 配置灰度
+
+### 4.1 场景
+
+某配置变更 → 10% 租户先验证。
+
+### 4.2 灰度规则
+
+```yaml
+config:
+  gray:
+    enabled: true
+    rule: "tenant_id IN ('T001', 'T002', 'T003')"   # 灰度租户列表
+```
+
+灰度租户用新值；其他用旧值。
+
+### 4.3 灰度 → 全量
+
+```java
+// 1. 开启灰度（部分租户新值）
+configService.setForTenant(code, newValue, "T001");
+
+// 2. 监控（指标 / 告警）
+configMonitorService.checkHealth();
+
+// 3. 全量（推所有租户）
+configService.setForAllTenants(code, newValue);
+```
+
+## 5. 配置版本
+
+### 5.1 历史版本
+
+```sql
+CREATE TABLE t_config_version (
+    id BIGINT PRIMARY KEY,
+    config_code VARCHAR(100),
+    version INT,
+    value TEXT,
+    operator_id VARCHAR(50),
+    effective_time DATETIME,
+    expire_time DATETIME,
+    INDEX idx_code_version (config_code, version)
+);
+```
+
+### 5.2 回滚
+
+```java
+@PostMapping("/admin/configs/{code}/rollback")
+public Result rollback(@PathVariable String code, @RequestParam int targetVersion) {
+    configService.rollback(code, targetVersion);
+    return Result.success();
+}
+```
+
+## 6. ❌ 反模式
+
+### 6.1 ❌ 租户配置覆盖错
+
+```java
+// ❌ 错
+configService.set("order.threshold", "50000");  // 默认 SYSTEM → 所有租户受影响
+```
+
+✅ 显式传 scope。
+
+### 6.2 ❌ 改配置不通知
+
+```java
+// ❌ 错
+configRepository.save(newConfig);  // 业务服务不知道值变了
+```
+
+✅ 发事件 → 业务订阅 → 清缓存。
+
+### 6.3 ❌ 无审计
+
+```java
+// ❌ 错：随便改配置
+// 排查问题时不知道谁改的
+```
+
+✅ 加审计。
+
+## 7. 关联阅读
+
+- [guide.md](guide.md) — 平台配置基础
+- [cache-and-persist.md](cache-and-persist.md) — 缓存策略
+- [SKILL.md](../SKILL.md)