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

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)

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

@@ -1,227 +0,0 @@
-# 合规扫描指南（2nd-dev-check）
-
-> 二开项目 9 条规则合规扫描命令与输出。
-
----
-
-## 1. 命令
-
-### 1.1 CLI
-
-```bash
-2nd-dev-check \
-  --project-dir=./my-2nd-service \
-  --rules=data-boundary,domain-model,code-spec \
-  --format=console
-```
-
-### 1.2 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--project-dir` | ✅ | 二开项目根目录 |
-| `--rules` | - | 规则集：`data-boundary,domain-model,code-spec,all` |
-| `--format` | - | `console` / `json` / `junit` |
-| `--output` | - | 报告输出文件 |
-| `--fail-on-warning` | - | warning 也退出码 1 |
-
-### 1.3 一键脚本
-
-```bash
-# 全量扫描
-bash tools/2nd-dev-check/run.sh ./my-2nd-service
-
-# 仅 data-boundary
-bash tools/2nd-dev-check/run.sh ./my-2nd-service --rules=data-boundary
-
-# JSON 报告
-bash tools/2nd-dev-check/run.sh ./my-2nd-service --format=json --output=report.json
-```
-
-## 2. 扫描规则集（9 条）
-
-详见 [rules-checklist.md](rules-checklist.md)。
-
-| # | 规则 | 来源 | 严重度 |
-|---|------|------|--------|
-| §1.1 | 不映射 PF_ 平台表 | data-boundary | 🔴 阻断 |
-| §1.2 | 不分页循环 Feign | data-boundary | 🔴 阻断 |
-| §1.3 | 不复制平台 Entity | data-boundary | 🔴 阻断 |
-| §1.4 | 不掩盖平台故障 | data-boundary | 🔴 阻断 |
-| §2.1 | 表/字段小写蛇形 | domain-model | 🔴 阻断 |
-| §2.2 | 不用名称做关联 | domain-model | 🔴 阻断 |
-| §2.3 | 跨服务禁外键 | domain-model | 🔴 阻断 |
-| §3.1 | 软删除穿透校验 | code-spec §八 | 🔴 阻断 |
-| §3.2 | 敏感信息不打印 | code-spec §敏感信息 | 🔴 阻断 |
-
-## 3. 输出格式
-
-### 3.1 console（默认）
-
-```
-========================================
-  MeritData 二开合规扫描
-========================================
-
-扫描目录：./my-2nd-service
-规则集：data-boundary, domain-model, code-spec
-时间：2026-09-07 10:30:00
-
-----------------------------------------
-§1.1 不映射 PF_ 平台表           ✅ 通过
-§1.2 不分页循环 Feign           ✅ 通过
-§1.3 不复制平台 Entity          ✅ 通过
-§1.4 不掩盖平台故障             ✅ 通过
-§2.1 表/字段小写蛇形            ❌ 失败
-§2.2 不用名称做关联             ✅ 通过
-§2.3 跨服务禁外键               ✅ 通过
-§3.1 软删除穿透校验             ✅ 通过
-§3.2 敏感信息不打印             ⚠️ 警告
-
-----------------------------------------
-  1 个失败，1 个警告
-----------------------------------------
-
-【§2.1 失败】
-文件: src/main/java/com/example/order/entity/Order.java:15
-规则: 表/字段小写蛇形
-详情: @TableName("T_Order") 应用 t_order
-建议: 改为 @TableName("t_order")
-
-【§3.2 警告】
-文件: src/main/java/com/example/order/service/OrderService.java:42
-规则: 敏感信息不打印
-详情: 日志包含 password 字段
-建议: 使用 @LogMask 注解或脱敏
-
-----------------------------------------
-扫描失败，阻断 PR ❌
-```
-
-### 3.2 JSON
-
-```json
-{
-  "scanTime": "2026-09-07T10:30:00Z",
-  "projectDir": "./my-2nd-service",
-  "rules": ["data-boundary", "domain-model", "code-spec"],
-  "summary": {
-    "total": 9,
-    "passed": 7,
-    "failed": 1,
-    "warnings": 1,
-    "exitCode": 1
-  },
-  "results": [
-    {
-      "rule": "§2.1",
-      "status": "FAILED",
-      "severity": "BLOCK",
-      "file": "src/main/java/com/example/order/entity/Order.java",
-      "line": 15,
-      "detail": "@TableName(\"T_Order\")",
-      "fix": "@TableName(\"t_order\")"
-    },
-    {
-      "rule": "§3.2",
-      "status": "WARNING",
-      "severity": "WARN",
-      "file": "src/main/java/com/example/order/service/OrderService.java",
-      "line": 42,
-      "detail": "日志包含 password",
-      "fix": "使用 @LogMask"
-    }
-  ]
-}
-```
-
-## 4. 退出码
-
-| 退出码 | 含义 |
-|--------|------|
-| 0 | 全部通过 |
-| 1 | 有失败（阻断）|
-| 2 | 仅警告 |
-| 3 | 扫描错误（无法执行）|
-
-## 5. 集成 CI
-
-详见 [ci-integration.md](ci-integration.md)。
-
-```yaml
-# GitLab CI
-compliance:
-  stage: check
-  script:
-    - bash tools/2nd-dev-check/run.sh ./ --format=junit --output=report.xml
-  artifacts:
-    reports:
-      junit: report.xml
-```
-
-## 6. ❌ 常见扫描误报
-
-### 6.1 ❌ 注释里的 PF_
-
-```java
-// 业务表 t_user 对应平台 PF_USER 字段 user_id
-```
-
-✅ 扫描器应忽略注释。
-
-### 6.2 ❌ 测试代码里的违规
-
-```java
-@Test
-void testBad() {
-    catch (Exception e) { return Collections.emptyList(); }  // 测试模拟
-}
-```
-
-✅ 用 `--exclude=src/test/` 跳过。
-
-### 6.3 ❌ 工具类里的 SQL
-
-```java
-// Utils 中拼接 SQL
-public class SqlUtils {
-    public static String buildWhere(String name) {
-        return "name = '" + name + "'";  // 工具，不是业务
-    }
-}
-```
-
-✅ 加白名单：`--whitelist=com.example.SqlUtils`。
-
-## 7. 自定义规则
-
-### 7.1 添加新规则
-
-创建 `tools/2nd-dev-check/rules/my-rule.yaml`：
-
-```yaml
-- id: MY-RULE-001
-  name: 不允许使用过时的日期 API
-  severity: BLOCK
-  pattern:
-    type: regex
-    regex: 'new Date\('
-    exclude: ['test/', 'mock/']
-  message: 使用 java.time.LocalDateTime 替代
-  fix: 'LocalDateTime.now()'
-```
-
-### 7.2 加载自定义规则
-
-```bash
-2nd-dev-check \
-  --project-dir=. \
-  --rules=data-boundary,domain-model \
-  --custom-rules=./rules/my-rule.yaml
-```
-
-## 8. 关联阅读
-
-- [rules-checklist.md](rules-checklist.md) — 9 条规则清单
-- [ci-integration.md](ci-integration.md) — CI 集成
-- [SKILL.md](../SKILL.md)