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

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

@@ -0,0 +1,296 @@
+# 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/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: meritdata-platform-2nd-dev-check
+description: 二开项目合规扫描（4 铁律 + 命名 + 软删除）。当用户说"二开合规 / 平台合规 / 合规扫描 / 上线检查 / check / lint"时使用。
+metadata:
+  version: "1.0.0"
+  risk: low
+  layer: L4
+  sub-layer: L4-T
+  stack: tool
+---
+
+# meritdata-platform-2nd-dev-check
+
+## 触发
+
+- 用户说"二开合规 / 上线检查 / 合规扫描 / lint"
+- PR 提交前 / 流水线门禁
+- 平台升级前兼容性扫描
+
+## 不触发
+
+- 业务逻辑 code review（→ `meritdata-platform-code-review`）
+- 数据访问深度审查（→ `meritdata-platform-data-access-review`）
+- 测试用例设计（→ `meritdata-platform-test-case`）
+
+## 前置约束
+
+- 扫描对象：二开服务的 `src/main/` 目录
+- 4 条铁律详情见 [`rules/meritdata-platform-data-boundary.md`](../../rules/meritdata-platform-data-boundary.md)
+- 5 条硬规则见 [`rules/meritdata-platform-domain-model-rules.md`](../../rules/meritdata-platform-domain-model-rules.md)
+- 软删除规则见 [`rules/code-dev-rules.md §八`](../../rules/code-dev-rules.md)
+- 违反**阻断 PR**（CI exit 1）
+
+## 路由
+
+- [guide.md](references/guide.md) — 命令清单 + 输出格式
+- [rules-checklist.md](references/rules-checklist.md) — 9 条规则逐条检查项
+- [ci-integration.md](references/ci-integration.md) — GitLab/GitHub Actions 集成

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

@@ -0,0 +1,307 @@
+# 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)