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

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

@@ -1,234 +0,0 @@
-# 配置缓存与持久化（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

@@ -1,225 +0,0 @@
-# 平台配置基础指南（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

@@ -1,254 +0,0 @@
-# 多租户配置与审计（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)