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

package/skills/meritdata-platform-data-access-review/references/anti-patterns.md

@@ -0,0 +1,287 @@
+# 反模式库（data-access-review）
+
+> 历史项目触发的真实反模式案例。每条含：场景 + 代码 + 后果 + 修复。
+
+---
+
+## 1. PF_ 平台表映射（§1.1）
+
+### 1.1 案例 A：业务库映射平台表
+
+**场景**：2026-03 项目，业务库直接映射 `PF_USER`。
+
+```java
+// ❌ 错
+@Entity
+@TableName("PF_USER")
+public class UserEntity {
+    private String id;
+    private String loginName;
+}
+```
+
+**后果**：
+- 平台升级失败（schema 变更冲突）
+- 数据库耦合，跨库事务
+- 性能压力转嫁
+
+**修复**：
+
+```java
+// ✅ 正确
+@FeignClient(name = "cloud-system-manage")
+public interface IUserClient {
+    @GetMapping("/users/{id}")
+    UserDTO getById(@PathVariable String id);
+}
+```
+
+### 1.2 案例 B：跨库 JOIN
+
+```sql
+-- ❌ 错
+SELECT o.*, u.real_name
+FROM t_order o
+JOIN PF_USER u ON o.user_id = u.id
+WHERE o.status = 'PAID';
+```
+
+**修复**：应用层 join（Feign 批量 + 内存 join）。
+
+---
+
+## 2. 分页循环 Feign（§1.2）
+
+### 2.1 案例 A：循环调用 userClient
+
+**场景**：2026-04 项目，订单列表渲染时 N+1 Feign。
+
+```java
+// ❌ 错
+@GetMapping("/orders")
+public List<OrderVO> list() {
+    List<Order> orders = orderRepository.findAll();
+    for (Order o : orders) {
+        UserDTO user = userClient.getById(o.getUserId());  // N 次 Feign
+        o.setUserName(user.getRealName());
+    }
+    return orders;
+}
+```
+
+**后果**：
+- 1000 个订单 → 1000 次 Feign 调用
+- RT 从 100ms 变成 30s
+- 用户看到白屏
+
+**修复**：
+
+```java
+// ✅ 正确：批量装配
+@GetMapping("/orders")
+public List<OrderVO> list() {
+    List<Order> orders = orderRepository.findAll();
+
+    List<String> userIds = orders.stream()
+        .map(Order::getUserId).distinct()
+        .collect(Collectors.toList());
+
+    Map<String, UserDTO> userMap = userClient.listByIds(userIds).stream()
+        .collect(Collectors.toMap(UserDTO::getUserId, Function.identity()));
+
+    return orders.stream().map(o -> {
+        OrderVO vo = OrderVO.from(o);
+        UserDTO user = userMap.get(o.getUserId());
+        vo.setUserName(user != null ? user.getRealName() : "未知");
+        return vo;
+    }).collect(Collectors.toList());
+}
+```
+
+### 2.2 案例 B：嵌套循环
+
+```java
+// ❌ 错
+for (Dept dept : depts) {
+    for (User user : dept.getUsers()) {
+        for (Role role : user.getRoles()) {
+            // ... 每层都 Feign
+        }
+    }
+}
+```
+
+**修复**：批量取所有 role IDs → 一次 Feign → 内存 join。
+
+---
+
+## 3. 平台 Entity 引用（§1.3）
+
+### 3.1 案例 A：二开 import 平台 Entity
+
+**场景**：2026-05 项目，二开 Service 直接操作平台 Entity。
+
+```java
+// ❌ 错
+import com.meritdata.cloud.platform.entity.User;
+import com.meritdata.cloud.platform.repository.UserRepository;
+
+@Service
+public class UserService {
+    @Autowired
+    private UserRepository userRepository;  // 平台 Repository
+
+    public void updateUser(User user) {
+        userRepository.save(user);
+    }
+}
+```
+
+**后果**：
+- 二开服务与平台 Entity 强耦合
+- 平台 Entity 字段变更 → 二开代码编译失败
+- 平台独立部署受限
+
+**修复**：
+
+```java
+// ✅ 正确：DTO 转换
+@FeignClient(name = "cloud-system-manage")
+public interface IUserClient {
+    @PostMapping("/users")
+    UserDTO createUser(@RequestBody UserDTO user);
+}
+
+@Service
+public class UserService {
+    @Autowired
+    private IUserClient userClient;
+
+    public void updateUser(UserDTO user) {
+        userClient.updateUser(user);
+    }
+}
+```
+
+### 3.2 案例 B：Entity extends 平台 Entity
+
+```java
+// ❌ 错
+@Entity
+public class CustomUser extends User {  // 继承平台 Entity
+    private String customField;
+}
+```
+
+**修复**：完全独立建表 + DTO 转换。
+
+---
+
+## 4. 空集合掩盖异常（§1.4）
+
+### 4.1 案例 A：Feign 失败返回空
+
+**场景**：2026-06 项目，平台用户服务短暂不可用，业务返回空列表。
+
+```java
+// ❌ 错
+@GetMapping("/orders")
+public List<OrderVO> list() {
+    try {
+        List<Order> orders = orderRepository.findAll();
+        List<String> userIds = orders.stream().map(Order::getUserId).collect(toList());
+        List<UserDTO> users = userClient.listByIds(userIds);  // Feign 失败
+        // ...
+    } catch (Exception e) {
+        return Collections.emptyList();  // 掩盖故障
+    }
+}
+```
+
+**后果**：
+- 平台故障时业务页面白屏
+- 监控无告警（异常被吃掉）
+- 故障定位耗时长
+
+**修复**：
+
+```java
+// ✅ 正确：显式异常
+@GetMapping("/orders")
+public List<OrderVO> list() {
+    try {
+        // ...
+    } catch (FeignException e) {
+        log.error("平台用户服务调用失败", e);
+        alertService.send("USER_SERVICE_UNAVAILABLE", e);
+        throw new ServiceException("USER_SERVICE_UNAVAILABLE", e);
+    }
+}
+```
+
+### 4.2 案例 B：空 catch
+
+```java
+// ❌ 错
+try {
+    userClient.updateUser(user);
+} catch (Exception e) {
+    // 吞掉
+}
+```
+
+**修复**：至少 log.error + 考虑 rethrow。
+
+---
+
+## 5. 其他反模式（非铁律）
+
+### 5.1 SQL 拼接
+
+```java
+// ❌ 错
+String sql = "SELECT * FROM t_user WHERE name = '" + name + "'";
+// → SQL 注入
+```
+
+✅ 用 `@Param` / `PreparedStatement`。
+
+### 5.2 循环内 DB 查询
+
+```java
+// ❌ 错
+for (String id : ids) {
+    userRepository.findById(id);  // 100 次查询
+}
+```
+
+✅ `findAllById(ids)`。
+
+### 5.3 同步 Feign 阻塞
+
+```java
+// ❌ 错
+UserDTO user = userClient.getById(id);  // 阻塞业务
+```
+
+✅ 异步 Feign 或预加载。
+
+---
+
+## 6. 总结表
+
+| 铁律 | 反模式 | 案例 | 严重度 |
+|------|--------|------|--------|
+| §1.1 | `@TableName("PF_")` | 2026-03 项目 | 🔴 |
+| §1.1 | 跨库 JOIN | 持续多项目 | 🔴 |
+| §1.2 | 循环 + Feign | 2026-04 项目 | 🔴 |
+| §1.3 | import 平台 Entity | 2026-05 项目 | 🔴 |
+| §1.3 | Entity 继承 | 持续 | 🔴 |
+| §1.4 | catch + emptyList | 2026-06 项目 | 🔴 |
+
+## 7. 关联阅读
+
+- [guide.md](guide.md) — 审查清单
+- [ci-scan.md](ci-scan.md) — CI 脚本
+- [rules/meritdata-platform-data-boundary.md](../../rules/meritdata-platform-data-boundary.md)
+- [SKILL.md](../SKILL.md)

package/skills/meritdata-platform-data-access-review/references/ci-scan.md

@@ -0,0 +1,225 @@
+# CI 扫描脚本（data-access-review）
+
+> 集成到 CI 的自动化扫描脚本，PR 触发时执行。
+
+---
+
+## 1. 集成方式
+
+### 1.1 GitLab CI
+
+```yaml
+# .gitlab-ci.yml
+data-access-review:
+  stage: check
+  script:
+    - bash scripts/scan-data-access.sh
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+```
+
+### 1.2 GitHub Actions
+
+```yaml
+# .github/workflows/data-access-review.yml
+name: Data Access Review
+on: [pull_request]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: bash scripts/scan-data-access.sh
+```
+
+## 2. 主脚本
+
+```bash
+#!/bin/bash
+# scripts/scan-data-access.sh
+# 数据访问 4 铁律扫描
+
+set -e
+SCAN_DIR="${1:-src/main}"
+EXIT_CODE=0
+
+echo "========================================="
+echo "  数据访问 4 铁律扫描"
+echo "========================================="
+
+# §1.1 PF_ 平台表
+echo ""
+echo "[§1.1] 检查 PF_ 平台表映射..."
+if grep -rE '@TableName\("PF_' "$SCAN_DIR"/java/ 2>/dev/null; then
+    echo "❌ 发现 PF_ 映射，违反铁律 1.1"
+    EXIT_CODE=1
+else
+    echo "✅ 未发现 PF_ 映射"
+fi
+
+# §1.1 跨库 JOIN
+echo ""
+echo "[§1.1] 检查跨库 JOIN 平台表..."
+if grep -rE 'JOIN\s+PF_' "$SCAN_DIR"/resources/mapper/ 2>/dev/null; then
+    echo "❌ 发现跨库 JOIN，违反铁律 1.1"
+    EXIT_CODE=1
+else
+    echo "✅ 未发现跨库 JOIN"
+fi
+
+# §1.3 平台 Entity
+echo ""
+echo "[§1.3] 检查平台 Entity 直接 import..."
+if grep -r 'import com.meritdata.cloud.platform.entity' "$SCAN_DIR"/java/com/example/ 2>/dev/null; then
+    echo "❌ 二开项目不应直接 import 平台 Entity"
+    EXIT_CODE=1
+else
+    echo "✅ 未发现平台 Entity 直接引用"
+fi
+
+# §1.4 空集合掩盖（warn 不阻断）
+echo ""
+echo "[§1.4] 检查空集合掩盖异常..."
+if grep -rn 'catch.*Exception.*emptyList\|catch.*Exception.*Collections.empty' "$SCAN_DIR"/java/ 2>/dev/null | grep -v 'test/'; then
+    echo "⚠️ 疑似空集合掩盖异常，请人工 review"
+else
+    echo "✅ 未发现空集合掩盖"
+fi
+
+echo ""
+echo "========================================="
+if [ $EXIT_CODE -eq 0 ]; then
+    echo "  扫描通过 ✅"
+else
+    echo "  扫描失败 ❌（请修复后重新提交）"
+fi
+echo "========================================="
+
+exit $EXIT_CODE
+```
+
+## 3. 高级扫描
+
+### 3.1 N+1 检测（AST）
+
+```python
+#!/usr/bin/env python3
+# scripts/scan-n-plus-one.py
+"""
+检测循环 + Feign.method() 模式（N+1 查询）
+"""
+import os
+import re
+import sys
+
+PATTERN = re.compile(
+    r'for\s*\(.*?\)\s*{[^}]*?(feignClient|userClient|orgClient|menuClient)\.\w+\(',
+    re.DOTALL
+)
+
+def scan_file(path):
+    with open(path) as f:
+        content = f.read()
+    return PATTERN.findall(content)
+
+def main():
+    violations = []
+    for root, _, files in os.walk('src/main/java'):
+        for f in files:
+            if f.endswith('.java'):
+                path = os.path.join(root, f)
+                matches = scan_file(path)
+                if matches:
+                    violations.append((path, matches))
+
+    if violations:
+        print("❌ 发现 N+1 模式：")
+        for path, matches in violations:
+            print(f"  {path}: {matches}")
+        sys.exit(1)
+    print("✅ 未发现 N+1 模式")
+
+if __name__ == '__main__':
+    main()
+```
+
+### 3.2 SQL 注入检测
+
+```bash
+#!/bin/bash
+# 检测 SQL 拼接
+echo "[SQL 注入] 检查字符串拼接 SQL..."
+
+# 检测 ${...} 在 @Query 注解中
+if grep -rn '@Query.*\${' src/main/java/ 2>/dev/null; then
+    echo "❌ 发现 @Query 中使用 \${} 拼接 SQL"
+    exit 1
+fi
+
+# 检测 Statement.executeQuery(string)
+if grep -rn 'executeQuery(".*" + ' src/main/java/ 2>/dev/null; then
+    echo "❌ 发现字符串拼接执行 SQL"
+    exit 1
+fi
+
+echo "✅ SQL 注入扫描通过"
+```
+
+### 3.3 敏感信息检测
+
+```bash
+#!/bin/bash
+# 检测硬编码密钥/密码
+echo "[敏感信息] 检查硬编码密钥..."
+
+PATTERNS=(
+    'password.*=.*"[a-zA-Z0-9]{6,}"'
+    'secret.*=.*"[a-zA-Z0-9]{8,}"'
+    'apiKey.*=.*"[a-zA-Z0-9]{16,}"'
+)
+
+for p in "${PATTERNS[@]}"; do
+    if grep -rEn "$p" src/main/java/ 2>/dev/null | grep -v 'test/'; then
+        echo "⚠️ 疑似硬编码密钥"
+    fi
+done
+
+echo "✅ 敏感信息扫描完成"
+```
+
+## 4. SonarQube 集成
+
+```xml
+<!-- sonar-project.properties -->
+sonar.projectKey=your-2nd-service
+sonar.sources=src/main/java
+sonar.exclusions=**/test/**,**/generated/**
+sonar.java.binaries=target/classes
+
+# 自定义规则
+sonar.custom_rules.java.data-access=java-data-access.xml
+```
+
+## 5. 报告输出
+
+```bash
+# 输出 JSON 格式报告
+{
+  "scanTime": "2026-09-07T10:00:00Z",
+  "rules": {
+    "1.1_pf_prefix": {"passed": true, "violations": []},
+    "1.1_cross_db_join": {"passed": true, "violations": []},
+    "1.3_platform_entity": {"passed": false, "violations": [...]},
+    "1.4_empty_collection": {"passed": true, "warnings": [...]}
+  },
+  "overall": "FAIL"
+}
+```
+
+## 6. 关联阅读
+
+- [guide.md](guide.md) — 审查清单
+- [anti-patterns.md](anti-patterns.md) — 反模式库
+- [rules/meritdata-platform-data-boundary.md §3](../../rules/meritdata-platform-data-boundary.md)
+- [SKILL.md](../SKILL.md)