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

package/skills/meritdata-nacos-importer/SKILL.md

@@ -1,37 +0,0 @@
----
-name: meritdata-nacos-importer
-description: 批量导入 Nacos 配置（YAML/Properties → Nacos 服务）。当用户说"导入 Nacos 配置 / 上线配置 / 批量同步 / 灰度发布"时使用。
-metadata:
-  version: "1.0.0"
-  risk: high
-  layer: L4
-  sub-layer: L4-T
-  stack: tool
----
-
-# meritdata-nacos-importer
-
-## 触发
-
-- 用户说"导入 Nacos 配置 / 上线配置 / 批量同步"
-- 用户提供 YAML/Properties 文件 + Nacos server + namespace
-- 灰度发布：先把配置推到"灰度命名空间"
-
-## 不触发
-
-- 单个 key 修改（→ Nacos 控制台 / API）
-- 配置中心架构问题（→ `meritdata-platform-nacos-config` skill）
-- 配置变更通知应用（→ `meritdata-platform-nacos-config` §shared-config）
-
-## 前置约束
-
-- 必须有 Nacos 服务地址 + 命名空间 ID + 访问凭证
-- 配置 key 命名遵守 [`rules/nacos-rules.md`](../../rules/nacos-rules.md)
-- 生产导入**必须先灰度**（PROD 命名空间单独审）
-- 大文件（>1MB）禁止推 Nacos（应用 `application-<env>.yml` 拆分）
-
-## 路由
-
-- [guide.md](references/guide.md) — 导入命令 + 工作流
-- [yaml-spec.md](references/yaml-spec.md) — YAML/Properties 文件规范
-- [gray-publish.md](references/gray-publish.md) — 灰度发布流程

package/skills/meritdata-nacos-importer/references/gray-publish.md

@@ -1,216 +0,0 @@
-# 灰度发布流程（nacos-importer）
-
-> Nacos 配置灰度发布的标准流程。
-
----
-
-## 1. 灰度发布 vs 全量发布
-
-| 维度 | 灰度发布 | 全量发布 |
-|------|---------|---------|
-| 范围 | 2-3 个实例 / 1 个 namespace | 全部实例 |
-| 风险 | 低（出问题只影响少量）| 高 |
-| 时间 | 长（分阶段）| 短（一次性）|
-| 适用 | 重要配置 / 不可逆操作 | 普通配置 / 可回滚 |
-
-## 2. 灰度命名空间
-
-### 2.1 创建
-
-在 Nacos 控制台：
-
-```
-命名空间名: gray-20260907-<变更主题>
-命名空间ID: 自动生成（复制用）
-描述: <变更原因>，操作人：张三
-```
-
-### 2.2 命名规范
-
-```
-gray-<YYYYMMDD>-<变更简述>
-```
-
-例：
-- `gray-20260907-bpm-timeout`
-- `gray-20260907-datasource-url`
-
-## 3. 灰度发布流程
-
-```
-1. 准备
-   ├─ 创建 PR / 评审
-   ├─ 创建 gray-xxx 命名空间
-   └─ 通知相关方
-
-2. 推送灰度
-   └─ nacos-import --namespace=gray-20260907-bpm-timeout
-
-3. 应用接入灰度
-   ├─ @NacosValue(group="gray-20260907-bpm-timeout")
-   └─ 或 spring.cloud.nacos.config.namespace=gray-20260907-bpm-timeout
-
-4. 验证（30 min）
-   ├─ 监控 / 日志 / 业务指标
-   ├─ 1-3 个实例跑灰度
-   └─ 通过 → 5 → 不通过 → 6.1
-
-5. 全量发布
-   ├─ nacos-import --namespace=prod
-   ├─ 监控所有实例
-   └─ 通过 → 6.2 / 不通过 → 6.1
-
-6. 收尾
-   ├─ 6.1 回滚：删除灰度 / 生产配置
-   └─ 6.2 清理：删除灰度命名空间
-```
-
-## 4. 配置示例
-
-### 4.1 应用端按 group 拉取
-
-```java
-@NacosValue(
-    value = "${order.timeout-seconds:30}",
-    group = "gray-20260907-bpm-timeout",  // 灰度
-    autoRefreshed = true
-)
-private int timeoutSeconds;
-```
-
-### 4.2 完整 namespace 切换
-
-```yaml
-# bootstrap.yml
-spring:
-  cloud:
-    nacos:
-      config:
-        namespace: gray-20260907-bpm-timeout  # 灰度
-```
-
-## 5. 监控指标
-
-| 指标 | 正常范围 | 异常处理 |
-|------|---------|---------|
-| 配置拉取成功率 | ≥ 99.9% | < 99% 立即回滚 |
-| 应用启动失败率 | < 0.1% | > 1% 回滚 |
-| 业务 RT (P95) | 持平 | 上升 > 50% 评估 |
-| 业务错误率 | 持平 | 上升 > 0.1% 回滚 |
-| 数据库连接 | 正常 | 异常立即回滚 |
-
-## 6. 回滚策略
-
-### 6.1 立即回滚
-
-```bash
-# 删除灰度命名空间配置（应用自动 fallback 到 prod）
-nacos-import --namespace=gray-20260907-bpm-timeout --skip-existing
-
-# 或手动删除
-curl -X DELETE "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=...&group=..."
-```
-
-### 6.2 全量回滚
-
-```bash
-# 备份当前 prod 配置
-nacos-export --namespace=prod --output=./backup-before-rollback
-
-# 恢复上一个版本
-nacos-import --namespace=prod --input-dir=./backup-before-rollback --skip-existing
-```
-
-## 7. CHANGELOG 模板
-
-```markdown
-## [YYYY-MM-DD] 配置变更
-
-**变更主题**：BPM 流程超时从 30s 改为 60s
-**变更人**：张三
-**灰度 ID**：gray-20260907-bpm-timeout
-**影响范围**：所有 BPM 流程
-
-**变更前**：
-```yaml
-meritdata:
-  bpm:
-    timeout-seconds: 30
-```
-
-**变更后**：
-```yaml
-meritdata:
-  bpm:
-    timeout-seconds: 60
-```
-
-**验证**：
-- 监控：✓ RT 持平
-- 业务：✓ 流程跑通
-- 错误率：✓ 无上升
-
-**回滚**：删除 gray-20260907-bpm-timeout 命名空间
-```
-
-## 8. ❌ 反模式
-
-### 8.1 ❌ 直接改生产命名空间
-
-```
-1. 改 prod/...
-2. 应用立即生效
-3. 出问题没回滚机会
-```
-
-✅ 用灰度命名空间。
-
-### 8.2 ❌ 灰度过长
-
-```
-灰度 3 天 → 没人验证 → 错过最佳窗口
-```
-
-✅ 灰度 ≤ 24h，及时收尾。
-
-### 8.3 ❌ 没有验证指标就全量
-
-```bash
-# ❌ 错
-nacos-import --namespace=prod  # 没验证
-```
-
-✅ 先灰度 → 验证 → 全量。
-
-### 8.4 ❌ 没备份
-
-```bash
-# ❌ 错：导入前没备份
-nacos-import --namespace=prod --input-dir=./new-config
-# 旧配置丢了
-```
-
-✅ 先 `nacos-export` 备份。
-
-## 9. 紧急回滚 SOP
-
-```
-发现生产异常
-  ↓
-1. 立即：删除新推的配置
-   curl -X DELETE "http://.../configs?dataId=..."
-
-2. 应用自动 fallback 到默认值 / 上次配置
-
-3. 通知：群 / 邮件 / 告警
-
-4. 记录事故：时间 / 影响 / 根因
-
-5. 修复 → 重新灰度
-```
-
-## 10. 关联阅读
-
-- [guide.md](guide.md) — 导入指南
-- [yaml-spec.md](yaml-spec.md) — YAML 规范
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-nacos-importer/references/guide.md

@@ -1,203 +0,0 @@
-# Nacos 导入指南（nacos-importer）
-
-> YAML/Properties 文件批量导入 Nacos 服务。
-
----
-
-## 1. 命令
-
-### 1.1 CLI 工具
-
-```bash
-nacos-import \
-  --server-addr=127.0.0.1:8848 \
-  --namespace=b8a8-xxx-dev \
-  --username=nacos \
-  --password=nacos \
-  --input-dir=./configs/dev \
-  --format=yaml
-```
-
-### 1.2 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--server-addr` | ✅ | Nacos 地址 |
-| `--namespace` | ✅ | 命名空间 ID（不是名称）|
-| `--username` | ✅ | 用户名 |
-| `--password` | ✅ | 密码 |
-| `--input-dir` | ✅ | 输入目录 |
-| `--format` | ✅ | `yaml` / `properties` |
-| `--dry-run` | - | 仅预览，不推送 |
-| `--skip-existing` | - | 跳过已存在 key |
-
-### 1.3 一键命令
-
-```bash
-# 推送到 dev
-./scripts/nacos-import.sh dev
-
-# 推送到生产（必须二次确认）
-./scripts/nacos-import.sh prod --confirm
-```
-
-## 2. 工作流
-
-```
-1. 本地 YAML/Properties 文件
-       ↓
-2. nacos-import CLI
-       ↓
-3. Nacos Open API
-       ↓
-4. Nacos 服务（命名空间隔离）
-       ↓
-5. 应用 @NacosValue / @ConfigurationProperties 拉取
-```
-
-## 3. 输入目录结构
-
-```
-configs/
-├── dev/
-│   ├── my-2nd-service.yaml        ← DataId: my-2nd-service.yaml
-│   ├── my-2nd-service-redis.yaml  ← DataId: my-2nd-service-redis.yaml
-│   └── common-shared.yaml         ← DataId: common-shared.yaml
-├── test/
-└── prod/
-```
-
-**DataId 命名**：`<spring.application.name>[-<suffix>].<format>`
-
-例：`my-2nd-service.yaml`、`my-2nd-service-redis.yaml`
-
-## 4. YAML 文件格式
-
-```yaml
-# configs/dev/my-2nd-service.yaml
-spring:
-  datasource:
-    url: jdbc:mysql://127.0.0.1:3306/order_dev
-    username: order
-    password: order123
-    hikari:
-      maximum-pool-size: 20
-
-server:
-  port: 8080
-
-meritdata:
-  bpm:
-    enabled: true
-```
-
-**注意**：
-
-- ✅ YAML 用 `:` 后空格
-- ✅ 嵌套用缩进
-- ❌ 不要包含 `---` 分隔符
-- ❌ 不要使用 YAML 锚点 `&` `*`（Nacos 不支持）
-
-## 5. 应用端拉取
-
-```yaml
-# bootstrap.yml
-spring:
-  application:
-    name: my-2nd-service
-  cloud:
-    nacos:
-      config:
-        server-addr: 127.0.0.1:8848
-        file-extension: yaml
-        namespace: b8a8-xxx-dev
-```
-
-```java
-@RestController
-public class OrderController {
-
-    @NacosValue(value = "${order.max-amount:10000}", autoRefreshed = true)
-    private BigDecimal maxAmount;
-
-    // ...
-}
-```
-
-## 6. 灰度发布
-
-详见 [gray-publish.md](gray-publish.md)。
-
-简版流程：
-
-```
-1. 准备灰度命名空间（如 gray-20260907）
-2. 把要发布的配置推到灰度命名空间
-3. 通知应用：@NacosValue(group="gray-20260907") 拉灰度
-4. 验证：监控 / 日志 / 业务指标
-5. 通过 → 推到生产命名空间
-6. 回滚 → 直接删除生产 / 灰度配置
-```
-
-## 7. ❌ 常见错误
-
-### 7.1 ❌ 命名空间 ID 错
-
-```
-ERROR: namespace 'dev' not found
-```
-
-✅ 用命名空间 ID（UUID 格式），不是名称。
-
-### 7.2 ❌ DataId 含非法字符
-
-```
-ERROR: dataId 'MY-SERVICE.YAML' invalid
-```
-
-✅ DataId 只允许小写字母、数字、`-`、`.`。
-
-### 7.3 ❌ 配置被覆盖未察觉
-
-```bash
-# ❌ 错：导入后没备份
-nacos-import ...  # 覆盖生产配置
-```
-
-✅ 用 `--skip-existing` 防止覆盖，或先备份：
-
-```bash
-nacos-export --namespace=prod --output=./backup-$(date +%Y%m%d)
-nacos-import --namespace=prod ...
-```
-
-### 7.4 ❌ 大文件超过限制
-
-```
-ERROR: content size 2097152 exceeds limit 102400
-```
-
-✅ 拆分配置：拆成 `my-2nd-service-db.yaml` + `my-2nd-service-redis.yaml` + ...
-
-## 8. 安全规范
-
-### 8.1 ✅ 通过 Nacos Open API
-
-```bash
-curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs" \
-  -d "dataId=my-2nd-service.yaml&group=DEFAULT_GROUP&content=..."
-```
-
-### 8.2 ❌ 不在 Nacos 控制台手动改生产
-
-| ❌ 反模式 | ✅ 正确 |
-|----------|--------|
-| 手动改 Nacos Web | Git 仓库管理 → nacos-importer |
-| 无变更记录 | 有 PR / commit / 操作日志 |
-| 多人手改冲突 | 自动化、单一来源 |
-
-## 9. 关联阅读
-
-- [yaml-spec.md](yaml-spec.md) — YAML 规范
-- [gray-publish.md](gray-publish.md) — 灰度发布
-- [SKILL.md](../SKILL.md)