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

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

@@ -0,0 +1,227 @@
+# 合规扫描指南（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)

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

@@ -0,0 +1,250 @@
+# 9 条规则清单（2nd-dev-check）
+
+> 9 条规则逐条检查项与检测方法。
+
+---
+
+## data-boundary（4 条）
+
+### §1.1 不映射 PF_ 平台表
+
+**规则**：二开业务库**不得**映射 `PF_` 前缀平台表。
+
+**检测**：
+
+```bash
+# 1. @TableName 注解
+grep -rE '@TableName\("PF_' src/main/java/
+
+# 2. CREATE TABLE 包含 PF_
+grep -rE 'CREATE TABLE PF_' src/main/resources/
+
+# 3. 跨库 JOIN
+grep -rE 'JOIN\s+PF_' src/main/resources/mapper/
+
+# 4. @Column 映射 PF_ 字段
+grep -rE '@Column\("PF_' src/main/java/
+```
+
+**通过条件**：以上 4 个命令**均无输出**。
+
+**修复**：改用 Feign Client 访问平台表。
+
+### §1.2 不分页循环逐条 Feign
+
+**规则**：循环内不得逐条调用 Feign Client。
+
+**检测**：
+
+```bash
+# 检测 for + feignClient.method() 模式
+grep -rE 'for\s*\(.*\)\s*{[^}]*feignClient\.\w+\(' src/main/java/ \
+  | grep -v 'test/'
+```
+
+**AST 高级检测**：
+
+```python
+# 检测三层嵌套循环 + Feign
+for (Page p : pages) {
+    for (Data d : p.getData()) {
+        feignClient.method(d.getId());  # N+1
+    }
+}
+```
+
+**通过条件**：检测无输出。
+
+**修复**：批量装配：`feignClient.listByIds(ids)` + 内存 join。
+
+### §1.3 不复制平台 Entity
+
+**规则**：二开代码不得 `import` 平台 Entity。
+
+**检测**：
+
+```bash
+grep -r 'import com.meritdata.cloud.platform.entity' src/main/java/com/example/
+
+# 也包括同包私有引用
+grep -r 'com.meritdata.cloud.platform.entity' src/main/java/com/example/ | grep import
+```
+
+**例外**：同 JVM 部署 + 明确引入 `cloud-system-manage-module`。
+
+**通过条件**：无 import。
+
+**修复**：用 DTO 转换 / Feign 接收。
+
+### §1.4 不掩盖平台故障
+
+**规则**：Feign 失败**不得**用空集合掩盖。
+
+**检测**：
+
+```bash
+# catch + emptyList
+grep -rn 'catch.*Exception.*emptyList\|catch.*Exception.*Collections.empty' src/main/java/ \
+  | grep -v 'test/'
+
+# 空 catch 块
+grep -rE 'catch\s*\([^)]+\)\s*{\s*}' src/main/java/ \
+  | grep -v 'test/'
+```
+
+**通过条件**：无输出。
+
+**修复**：显式 `throw new ServiceException(...)`。
+
+---
+
+## domain-model（3 条）
+
+### §2.1 表/字段小写蛇形
+
+**规则**：二开业务表/字段必须小写蛇形，以 `t_` 开头。
+
+**检测**：
+
+```bash
+# 大写表名
+grep -rE 'CREATE TABLE [A-Z]' src/main/resources/
+
+# @TableName 大写
+grep -rE '@TableName\("[A-Z]' src/main/java/
+
+# @Column 字段名大写
+grep -rE '@Column\("[A-Z]' src/main/java/
+```
+
+**通过条件**：无输出。
+
+**修复**：表名 `t_order`、字段 `order_no`、实体类 `Order`（驼峰）+ `@Column("order_no")` 显式映射。
+
+### §2.2 不用名称做关联
+
+**规则**：不得用姓名/组织名做关联键。
+
+**检测**：
+
+```bash
+# SQL JOIN/WHERE 含 _name 关联
+grep -rE 'WHERE.*_[a-z]+_name\s*=|ON.*\.[a-z]+_name\s*=' src/main/resources/mapper/
+
+# Java @Query 含 name 关联
+grep -rE '@Query.*WHERE.*_name\s*=' src/main/java/
+```
+
+**通过条件**：无输出。
+
+**修复**：用 `*_user_id` / `*_dept_id` 稳定 ID。
+
+### §2.3 跨服务禁外键
+
+**规则**：跨服务禁止数据库外键。
+
+**检测**：
+
+```bash
+# ALTER TABLE ... FOREIGN KEY ... REFERENCES
+grep -rE 'FOREIGN KEY.*REFERENCES\s+\w+\.\w+' src/main/resources/ \
+  | grep -v 'local_schema'
+```
+
+**通过条件**：无输出。
+
+**修复**：应用层维护一致性（ID 引用 + 服务编排）。
+
+---
+
+## code-spec（2 条）
+
+### §3.1 软删除穿透校验
+
+**规则**：软删除实体的唯一性校验**必须**走 `findXxxIncludingDeleted`。
+
+**检测**：
+
+```bash
+# 软删除实体 + JPQL 唯一性校验
+grep -rE '@SQLDelete' src/main/java/ > soft_delete_files.txt
+grep -rE 'findBy[A-Z]\w*No\b' src/main/java/ > find_no_files.txt
+# 求交集：同时含 @SQLDelete 和 findByXxxNo 的文件
+
+# 缺少 *IncludingDeleted 对应方法
+grep -rE 'findXxxIncludingDeleted' src/main/java/ > including_deleted.txt
+```
+
+**通过条件**：
+
+- 同时使用 `findByXxxNo` 和 `findXxxIncludingDeleted`
+- `findXxxIncludingDeleted` 是 `nativeQuery = true`
+- 唯一性校验用 `findXxxIncludingDeleted`
+
+**修复**：见 `code-dev-rules.md §八`。
+
+### §3.2 敏感信息不打印
+
+**规则**：日志**不得**包含 password / token / keytab。
+
+**检测**：
+
+```bash
+# 日志含敏感字段
+grep -rE 'log\.(info|debug|warn|error).*password|log\..*token|log\..*keytab' src/main/java/ \
+  | grep -v 'test/'
+
+# 硬编码密钥
+grep -rE '(password|secret|apiKey|token)\s*=\s*"[a-zA-Z0-9]{8,}"' src/main/java/ \
+  | grep -v 'test/'
+```
+
+**通过条件**：无输出。
+
+**修复**：
+
+- 日志用 `@LogMask` 自动脱敏
+- 密钥从 Nacos 配置：`@NacosValue(value = "${app.secret-key}")`
+
+---
+
+## 检测脚本汇总
+
+```bash
+#!/bin/bash
+# run.sh
+
+EXIT_CODE=0
+
+run_check() {
+    local name=$1
+    local cmd=$2
+    echo "[$name]"
+    if eval "$cmd"; then
+        echo "✅ 通过"
+    else
+        echo "❌ 失败"
+        EXIT_CODE=1
+    fi
+    echo ""
+}
+
+run_check "§1.1 PF_ 平台表" "! grep -rE '@TableName\(\"PF_' src/main/java/"
+run_check "§1.2 循环 Feign" "! grep -rE 'for\\s*\\(.*\\)\\s*{[^}]*feignClient\\.\\w+\\(' src/main/java/"
+run_check "§1.3 平台 Entity" "! grep -r 'import com.meritdata.cloud.platform.entity' src/main/java/com/example/"
+run_check "§1.4 空集合掩盖" "! grep -rn 'catch.*Exception.*emptyList' src/main/java/ | grep -v test/"
+run_check "§2.1 大写表名" "! grep -rE '@TableName\\(\"[A-Z]' src/main/java/"
+run_check "§2.2 名称关联" "! grep -rE 'WHERE.*_[a-z]+_name\\s*=' src/main/resources/mapper/"
+run_check "§2.3 跨服务外键" "! grep -rE 'FOREIGN KEY.*REFERENCES\\s+\\w+\\.\\w+' src/main/resources/ | grep -v local_schema"
+run_check "§3.1 软删除穿透" "[ -f rules/soft-delete.txt ] && grep -q IncludingDeleted rules/soft-delete.txt"
+run_check "§3.2 敏感信息" "! grep -rE 'log\\..*password' src/main/java/ | grep -v test/"
+
+exit $EXIT_CODE
+```
+
+## 关联阅读
+
+- [guide.md](guide.md) — 扫描指南
+- [ci-integration.md](ci-integration.md) — CI 集成
+- [rules/meritdata-platform-data-boundary.md](../../../rules/meritdata-platform-data-boundary.md)
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-backend-deploy/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: meritdata-platform-backend-deploy
+description: |
+  后端部署。Docker 镜像 / Kubernetes 部署 / 滚动发布 / 灰度 / 健康检查 / 配置注入 / 日志收集。
+  触发场景：后端服务上线部署 / 配置 K8s Deployment / 配置健康检查 / 灰度发布 / 自动扩缩容。
+  何时不用：前端部署 → 用 meritdata-platform-frontend-deploy；CI/CD 流水线 → 用 cicd skill。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: high
+  layer: L3
+  sub-layer: L3-C
+  stack: java
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 后端部署（backend-deploy）
+
+## 触发
+- 后端服务打包成 Docker 镜像
+- Kubernetes Deployment 配置
+- 滚动发布 / 蓝绿部署 / 灰度
+- 健康检查 / 探活配置
+- 配置注入（ConfigMap / Secret）
+- 日志收集 / 监控接入
+
+## 不触发
+- 前端部署 → 用 `meritdata-platform-frontend-deploy`
+- 业务代码 → 用开发 skill
+- 数据库变更 → 用 DBMigration skill
+
+## 前置约束
+- 镜像必须**多阶段构建**，基础镜像用官方 JDK
+- 健康检查**必须**配置（readinessProbe / livenessProbe）
+- 敏感配置**禁止**明文 → 用 Secret
+- 资源限制**必须**配置（CPU / Memory）
+
+## 路由
+- Docker + K8s 部署 → [references/guide.md](references/guide.md)
+- 灰度 / 滚动 / 蓝绿 → [references/release-strategies.md](references/release-strategies.md)
+- 健康检查 / 监控 / 日志 → [references/health-monitor-log.md](references/health-monitor-log.md)
+- [SKILL.md](../SKILL.md)