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

package/skills/meritdata-nacos-importer/references/yaml-spec.md

@@ -1,296 +0,0 @@
-# YAML/Properties 规范（nacos-importer）
-
-> 导入 Nacos 的配置文件规范。
-
----
-
-## 1. YAML 文件规范
-
-### 1.1 顶级结构
-
-```yaml
-# 一级 key 通常是 spring / server / meritdata / logging 等
-spring:
-  application:
-    name: my-2nd-service
-
-server:
-  port: 8080
-
-meritdata:
-  bpm:
-    enabled: true
-
-logging:
-  level:
-    com.example.order: DEBUG
-```
-
-### 1.2 缩进
-
-✅ **必须**：2 空格缩进
-❌ 禁止：Tab 缩进
-
-### 1.3 注释
-
-```yaml
-# 注释行
-spring:
-  # 嵌套注释
-  datasource:
-    url: jdbc:mysql://127.0.0.1:3306/order_dev  # 行尾注释
-```
-
-### 1.4 多行字符串
-
-```yaml
-# ✅ 用 | 保留换行
-description: |
-  这是多行
-  描述
-
-# ✅ 用 > 折叠换行
-summary: >-
-  这是长字符串
-  折叠为一行
-```
-
-## 2. 数据类型
-
-### 2.1 字符串
-
-```yaml
-# ✅ 显式引号
-name: "my-service"
-
-# ✅ 不带引号
-name: my-service
-
-# ✅ 含特殊字符必须引号
-pattern: "^[a-z]+$"
-```
-
-### 2.2 数字
-
-```yaml
-port: 8080
-max-pool-size: 20
-timeout: 30.5
-```
-
-### 2.3 布尔
-
-```yaml
-enabled: true
-disabled: false
-```
-
-### 2.4 列表
-
-```yaml
-# 短列表
-servers:
-  - 127.0.0.1:8848
-  - 127.0.0.1:8849
-
-# 嵌套列表
-endpoints:
-  - name: order
-    url: /api/v1/orders
-  - name: user
-    url: /api/v1/users
-```
-
-### 2.5 Map
-
-```yaml
-# 行内
-datasource: {url: jdbc:mysql://..., username: root}
-
-# 展开（推荐）
-datasource:
-  url: jdbc:mysql://...
-  username: root
-```
-
-### 2.6 空值
-
-```yaml
-# ✅ null / ~ / 不写
-password: null
-password: ~
-
-# ✅ 空字符串
-description: ""
-```
-
-## 3. ❌ 禁止使用
-
-### 3.1 ❌ YAML 锚点
-
-```yaml
-# ❌ 错：Nacos 不支持锚点
-defaults: &defaults
-  timeout: 30
-service-a:
-  <<: *defaults
-  url: /a
-```
-
-✅ 复制配置：
-
-```yaml
-service-a:
-  timeout: 30
-  url: /a
-```
-
-### 3.2 ❌ 文档分隔符
-
-```yaml
-# ❌ 错：Nacos 解析报错
-spring:
-  profiles: dev
----
-spring:
-  profiles: test
-```
-
-✅ 拆成多个文件。
-
-### 3.3 ❌ 复杂模板
-
-```yaml
-# ❌ 错：模板引擎语法
-url: ${DB_HOST:127.0.0.1}:${DB_PORT:3306}
-```
-
-✅ Nacos 用占位符在应用端替换：
-
-```yaml
-# Nacos 配置
-url: jdbc:mysql://${DB_HOST:127.0.0.1}:${DB_PORT:3306}/order_dev
-
-# 应用启动时传环境变量
-java -jar app.jar --DB_HOST=mysql.prod
-```
-
-## 4. Properties 文件规范
-
-### 4.1 基本格式
-
-```properties
-# 注释
-spring.datasource.url=jdbc:mysql://127.0.0.1:3306/order_dev
-spring.datasource.username=root
-spring.datasource.password=root
-```
-
-### 4.2 多行
-
-```properties
-# ✅ 用反斜杠续行
-description=这是一个很长的\
-              多行描述
-
-# ✅ 用 value 包含换行
-description=line1\nline2
-```
-
-### 4.3 特殊字符
-
-```properties
-# ✅ 用反斜杠转义
-url=jdbc:mysql://host\:port/db
-
-# ❌ 错：直接写特殊字符
-url=jdbc:mysql://host:port/db
-```
-
-## 5. 配置大小限制
-
-| 项 | 限制 |
-|----|------|
-| 单文件最大 | 100KB（Nacos 默认）|
-| 单 key 长度 | ≤ 1MB |
-| 嵌套层级 | ≤ 5 层 |
-
-超过需拆分：
-
-```yaml
-# ❌ 错：单文件超大
-my-2nd-service.yaml  # 5MB
-
-# ✅ 正确：按业务拆分
-my-2nd-service-db.yaml        # DB
-my-2nd-service-redis.yaml     # Redis
-my-2nd-service-mq.yaml        # MQ
-my-2nd-service-business.yaml  # 业务配置
-```
-
-## 6. 敏感信息
-
-### 6.1 ❌ 明文密码
-
-```yaml
-# ❌ 错
-spring:
-  datasource:
-    password: MyP@ssw0rd!
-```
-
-✅ 用 Nacos Config 加密：
-
-```yaml
-spring:
-  datasource:
-    password: ENC(xxx...)  # 加密值
-```
-
-或环境变量：
-
-```yaml
-spring:
-  datasource:
-    password: ${DB_PASSWORD}
-```
-
-### 6.2 ❌ 提交敏感信息到 git
-
-```bash
-# 检查
-git secrets --scan
-# 或
-grep -rE 'password.*=.*[a-zA-Z0-9]{8,}' configs/
-```
-
-## 7. 命名规范
-
-### 7.1 DataId
-
-```
-<spring.application.name>[-<suffix>].<format>
-```
-
-✅ `my-2nd-service.yaml` / `my-2nd-service-redis.yaml`
-❌ `MY-2ND-SERVICE.YAML`（大写）
-
-### 7.2 Group
-
-默认 `DEFAULT_GROUP`，灰度用 `GRAY_<日期>`。
-
-```
-DEFAULT_GROUP               # 默认
-GRAY_20260907               # 灰度
-```
-
-### 7.3 Key（Properties）
-
-✅ 全小写 + 点分隔：`spring.datasource.url`
-❌ 驼峰：`spring.datasource.jdbcUrl`
-
-## 8. 关联阅读
-
-- [guide.md](guide.md) — 导入指南
-- [gray-publish.md](gray-publish.md) — 灰度发布
-- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-2nd-dev-check/references/ci-integration.md

@@ -1,307 +0,0 @@
-# CI 集成（2nd-dev-check）
-
-> 集成到 GitLab CI / GitHub Actions / Jenkins。
-
----
-
-## 1. GitLab CI
-
-### 1.1 `.gitlab-ci.yml`
-
-```yaml
-stages:
-  - check
-  - test
-  - build
-
-compliance-check:
-  stage: check
-  image: meritdata/2nd-dev-check:latest
-  script:
-    - 2nd-dev-check --project-dir=. --format=junit --output=gl-report.xml
-  artifacts:
-    when: always
-    reports:
-      junit: gl-report.xml
-    paths:
-      - compliance-report.json
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-    - if: '$CI_COMMIT_BRANCH == "main"'
-```
-
-### 1.2 全量扫描（定时）
-
-```yaml
-nightly-compliance:
-  stage: check
-  image: meritdata/2nd-dev-check:latest
-  script:
-    - 2nd-dev-check --project-dir=. --rules=all --format=json --output=report-$(date +%Y%m%d).json
-  artifacts:
-    paths:
-      - report-*.json
-    expire_in: 30 days
-  rules:
-    - if: '$CI_PIPELINE_SOURCE == "schedule"'
-  only:
-    variables:
-      - $NIGHTLY_SCAN == "true"
-```
-
-## 2. GitHub Actions
-
-### 2.1 `.github/workflows/compliance.yml`
-
-```yaml
-name: Compliance Check
-
-on:
-  pull_request:
-  push:
-    branches: [main]
-
-jobs:
-  compliance:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Run 2nd-dev-check
-        uses: meritdata/2nd-dev-action@v1
-        with:
-          project-dir: '.'
-          rules: 'data-boundary,domain-model,code-spec'
-          format: 'github'
-
-      - name: Upload report
-        if: always()
-        uses: actions/upload-artifact@v3
-        with:
-          name: compliance-report
-          path: compliance-report.json
-```
-
-### 2.2 PR 评论机器人
-
-```yaml
-      - name: Comment PR
-        if: github.event_name == 'pull_request' && failure()
-        uses: actions/github-script@v6
-        with:
-          script: |
-            const report = require('./compliance-report.json');
-            const failed = report.results.filter(r => r.status === 'FAILED');
-
-            let body = '## ❌ 合规扫描失败\n\n';
-            failed.forEach(f => {
-              body += `- **${f.rule}** ${f.file}:${f.line}\n`;
-              body += `  - ${f.detail}\n`;
-              body += `  - 修复：${f.fix}\n`;
-            });
-
-            github.rest.issues.createComment({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              body: body
-            });
-```
-
-## 3. Jenkins
-
-### 3.1 Jenkinsfile
-
-```groovy
-pipeline {
-    agent any
-
-    stages {
-        stage('Compliance') {
-            steps {
-                sh '''
-                    docker run --rm \
-                      -v $(pwd):/project \
-                      meritdata/2nd-dev-check:latest \
-                      --project-dir=/project \
-                      --format=junit \
-                      --output=report.xml
-                '''
-            }
-        }
-    }
-
-    post {
-        always {
-            junit 'report.xml'
-        }
-    }
-}
-```
-
-## 4. 本地 pre-commit hook
-
-### 4.1 `.git/hooks/pre-commit`
-
-```bash
-#!/bin/bash
-# 二开合规 pre-commit
-
-echo "运行 2nd-dev-check..."
-bash tools/2nd-dev-check/run.sh .
-
-if [ $? -ne 0 ]; then
-    echo "❌ 合规扫描失败，提交被阻止"
-    exit 1
-fi
-```
-
-### 4.2 设置可执行
-
-```bash
-chmod +x .git/hooks/pre-commit
-```
-
-### 4.3 跳过（紧急）
-
-```bash
-git commit --no-verify  # 不推荐
-```
-
-## 5. 报告上传到平台
-
-### 5.1 上传到 MeritData 效能平台
-
-```bash
-2nd-dev-check \
-  --project-dir=. \
-  --format=json \
-  --output=report.json
-
-# 上传
-curl -X POST "https://efficiency.meritdata.com/api/compliance/upload" \
-  -H "Authorization: Bearer ${EFFICIENCY_TOKEN}" \
-  -F "project=${CI_PROJECT_NAME}" \
-  -F "branch=${CI_COMMIT_REF_NAME}" \
-  -F "commit=${CI_COMMIT_SHA}" \
-  -F "report=@report.json"
-```
-
-### 5.2 上传到 SonarQube
-
-```bash
-2nd-dev-check --format=sonar --output=sonar-report.json
-sonar-scanner \
-  -Dsonar.externalIssuesReportPaths=sonar-report.json
-```
-
-## 6. 失败处理
-
-### 6.1 单规则失败
-
-```bash
-# §1.1 PF_ 平台表 失败
-# 1. 查看详情
-2nd-dev-check --rules=data-boundary --verbose
-
-# 2. 修复
-# 把 @TableName("PF_USER") 改为 Feign Client
-
-# 3. 重跑
-2nd-dev-check --rules=data-boundary
-```
-
-### 6.2 阻断 PR
-
-PR 自动被阻止合并：
-
-```
-PR #1234 ❌ compliance-check failed
-  §2.1 表/字段小写蛇形 — 1 failure
-  
-[Details] Order.java:15 @TableName("T_Order") 应改为 @TableName("t_order")
-```
-
-需修复后重新推送。
-
-### 6.3 紧急豁免（仅限生产事故）
-
-```yaml
-# .gitlab-ci.yml 临时豁免
-compliance-check:
-  script:
-    - |
-      if [ "$EMERGENCY_HOTFIX" == "true" ]; then
-        echo "⚠️ 紧急豁免：跳过合规扫描"
-        exit 0
-      fi
-      2nd-dev-check --project-dir=.
-```
-
-## 7. 性能优化
-
-### 7.1 增量扫描
-
-```bash
-2nd-dev-check \
-  --project-dir=. \
-  --incremental \
-  --since-commit=HEAD~1
-```
-
-只扫描变更文件。
-
-### 7.2 并行
-
-```bash
-2nd-dev-check --parallel=4
-```
-
-### 7.3 缓存
-
-```yaml
-# .gitlab-ci.yml
-compliance-check:
-  cache:
-    key: 2nd-dev-check-${CI_COMMIT_REF_SLUG}
-    paths:
-      - .cache/2nd-dev-check/
-```
-
-## 8. ❌ 反模式
-
-### 8.1 ❌ 跳过 CI 扫描
-
-```yaml
-# ❌ 错
-compliance-check:
-  script: echo "skip"
-```
-
-✅ 必须跑扫描。
-
-### 8.2 ❌ 只在主分支跑
-
-```yaml
-# ❌ 错：MR 不跑，主分支出问题
-rules:
-  - if: '$CI_COMMIT_BRANCH == "main"'
-```
-
-✅ MR 必须跑。
-
-### 8.3 ❌ 失败不阻断
-
-```yaml
-# ❌ 错：失败也通过
-script:
-  - 2nd-dev-check --project-dir=. || true
-```
-
-✅ 必须 exit 1 → 阻断。
-
-## 9. 关联阅读
-
-- [guide.md](guide.md) — 扫描指南
-- [rules-checklist.md](rules-checklist.md) — 9 条规则
-- [SKILL.md](../SKILL.md)