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

package/skills/meritdata-platform-code-spec/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: meritdata-platform-code-spec
+description: |
+  代码规范方法论（编码层）。写完二开 Java/SQL/接口代码后做强制规范自查；PR review 时逐项打钩。仅当"刚写完/要改一段二开代码、需要做规范门禁"时加载。
+  何时不用：写第一行代码前不知道从哪里开始（用 playbook）；阅读他人代码理解逻辑（用对应业务 skill）。
+metadata:
+  version: "1.0.0"
+  author: petroleum+rd
+  source: petroleum+rd
+  date_added: "2026-09-07"
+  last_modified: "2026-09-07"
+  risk: low
+  layer: L2
+  sub-layer: L2-M
+  stack: methodology
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 代码规范方法论（code-spec）
+
+## 触发
+- 写完一段二开 Java 代码，提交前自查
+- PR review 需要逐项打钩
+- 准备生成 SQL / 接口代码，需要命名规范检查
+
+## 不触发
+- 写第一行代码前不知道从哪里开始 → 用 `meritdata-platform-playbook`
+- 阅读他人代码理解逻辑（不需要门禁）→ 用对应业务 skill
+- 纯前端样式 → 用 `meritdata-platform-frontend`
+
+## 前置约束
+- 所有铁律见 [rules/code-dev-rules.md §8.3](../../rules/code-dev-rules.md#83-code-spec-补充铁律编码层)
+
+## 路由
+- 反模式案例 + 正模式代码 → [references/anti-patterns.md](references/anti-patterns.md)
+- CI 检测命令（bash / GitHub Actions）→ [references/validate-rules.md](references/validate-rules.md)

package/skills/meritdata-platform-code-spec/references/anti-patterns.md

@@ -0,0 +1,533 @@
+# 反模式 vs 正模式（code-spec）
+
+> **本文件与 rules/code-dev-rules.md §八.3 一一对应**。每条铁律给出：❌ 反模式代码 → ✅ 正模式代码 → 根因 → 真实踩坑案例。
+>
+> **使用方法**：写代码时按目录逐项检查；PR review 时逐项打钩；CI 扫描时按 [validate-rules.md](validate-rules.md) 自动检测。
+
+---
+
+## 1. 软删除实体反模式（核心反模式）
+
+### 1.1 唯一性校验未穿透软删除
+
+**铁律来源**：[rules §八.3 软删除实体](../../../../rules/code-dev-rules.md#83-code-spec-补充铁律编码层)
+
+**触发条件**：实体使用 `@SQLDelete` + `@Where(clause="deleted=false")` + 任意 `uk_xxx_no` 唯一约束。
+
+#### ❌ 反模式（业务查询看不到软删除记录）
+
+```java
+public void createProject(String projectNo) {
+    // JPQL 受 @Where 过滤，看不到软删除记录
+    if (projectRepo.findByProjectNo(projectNo).isPresent()) {
+        throw new ProjectNoDuplicateException();
+    }
+    Project p = new Project();
+    p.setProjectNo(projectNo);
+    projectRepo.save(p);  // 💥 INSERT 触发 SQLIntegrityConstraintViolationException 500
+}
+```
+
+#### ✅ 正模式（nativeQuery + findIncludingDeleted）
+
+```java
+public void createProject(String projectNo) {
+    // nativeQuery = true 的 findIncludingDeleted 穿透 @Where 过滤
+    if (projectRepo.findProjectNoIncludingDeleted(projectNo).isPresent()) {
+        throw new ProjectNoDuplicateException();
+    }
+    Project p = new Project();
+    p.setProjectNo(projectNo);
+    projectRepo.save(p);  // ✅ DB 唯一约束检查通过后才 INSERT
+}
+```
+
+**Repository 实现要点**：
+
+```java
+// ❌ 错（JPQL，受 @Where 过滤）
+@Query("SELECT p FROM Project p WHERE p.projectNo = :no")
+Optional<Project> findByProjectNo(@Param("no") String no);
+
+// ✅ 对（nativeQuery = true，穿透过滤）
+@Query(value = "SELECT * FROM t_project WHERE project_no = :no AND deleted = :deleted",
+       nativeQuery = true)
+Optional<Project> findProjectNoIncludingDeleted(@Param("no") String no,
+                                                  @Param("deleted") boolean deleted);
+```
+
+#### 根因
+
+DB 唯一约束 `uk_project_no` 包含所有记录（含软删除），但业务 JPQL 受 `@Where(clause="deleted=false")` 过滤，业务查询看不到软删除记录 → 校验放行 → INSERT 触发唯一约束异常 500。
+
+#### 真实踩坑案例
+
+- **2026-06-12 Project 模块**：新增项目时复用软删除的项目编号，校验通过但 INSERT 500
+- **2026-06-12 Customer 模块**：同样的反模式，连续触发两次
+
+完整案例与回归用例见 `docs/技术约束.md §6`。
+
+### 1.2 编号生成器查已用编号
+
+**铁律来源**：同 §八.3 软删除实体
+
+#### ❌ 反模式
+
+```java
+// XxxNoGenerator.generate() 内部
+List<String> usedNos = repo.findAllNosStartingWith(prefix);  // 受 @Where 过滤
+// → 软删除的编号被认为"未用" → 生成可能重复 → 触发唯一约束
+```
+
+#### ✅ 正模式
+
+```java
+List<String> usedNos = repo.findAllNosStartingWithIncludingDeleted(prefix, nativeQuery = true);
+// → 软删除的编号计入已用 → 生成新编号自动跳过
+```
+
+### 1.3 业务查询与全量查询必须成对出现
+
+**铁律来源**：同 §八.3
+
+**命名约定**：
+
+| 业务查询（受 @Where 过滤）| 全量查询（穿透 @Where）|
+|--------------------------|------------------------|
+| `findByProjectNo` | `findProjectNoIncludingDeleted` |
+| `findAllByCreateBy` | `findAllByCreateByIncludingDeleted` |
+| `findAllXxxStartingWith` | `findAllXxxStartingWithIncludingDeleted` |
+
+**禁止**：
+- ❌ 用 `findByXxx` 做唯一性校验
+- ❌ 用 `*IncludingDeleted` 方法做业务展示（业务展示只允许走业务查询）
+
+---
+
+## 2. 循环与外部资源反模式
+
+**铁律来源**：[rules §四](../../../../rules/code-dev-rules.md#四流程控制) + §八.3
+
+### 2.1 循环内调数据库
+
+#### ❌ 反模式
+
+```java
+for (Order order : orders) {
+    User user = userDao.findById(order.getUserId());  // N 次查询
+    order.setUserName(user.getName());
+}
+```
+
+#### ✅ 正模式
+
+```java
+List<Long> userIds = orders.stream().map(Order::getUserId).distinct().collect(toList());
+Map<Long, User> userMap = userDao.findAllById(userIds).stream()
+    .collect(Collectors.toMap(User::getId, u -> u));
+orders.forEach(o -> {
+    User u = userMap.get(o.getUserId());
+    if (u != null) o.setUserName(u.getName());
+});
+```
+
+**理由**：N+1 查询导致响应时间随数据量线性恶化，数据库连接池耗尽。
+
+### 2.2 循环内调 Feign / HTTP
+
+#### ❌ 反模式
+
+```java
+for (int page = 1; page <= totalPages; page++) {
+    List<Order> orderList = orderRepo.findPage(page);
+    for (Order order : orderList) {
+        UserDTO user = userClient.getById(order.getUserId());  // N 次 Feign
+        order.setUserName(user.getName());
+    }
+}
+```
+
+#### ✅ 正模式
+
+```java
+// 一次 Feign 批量拉取
+List<Order> allOrders = orderRepo.findAll();
+Set<Long> userIds = allOrders.stream().map(Order::getUserId).collect(Collectors.toSet());
+Map<Long, UserDTO> userMap = userClient.listByIds(new ArrayList<>(userIds))
+    .stream().collect(Collectors.toMap(UserDTO::getId, u -> u));
+
+// 内存 join
+allOrders.forEach(o -> {
+    UserDTO u = userMap.get(o.getUserId());
+    if (u != null) o.setUserName(u.getName());
+});
+```
+
+**铁律 2 关联**：[data-boundary 反模式 §1.2](../meritdata-platform-data-boundary/references/anti-patterns.md#12-分页循环逐条-feign)
+
+### 2.3 循环内调 Redis / 缓存
+
+#### ❌ 反模式
+
+```java
+for (String key : keys) {
+    String value = redisTemplate.opsForValue().get(key);  // N 次 RTT
+    process(key, value);
+}
+```
+
+#### ✅ 正模式（pipeline）
+
+```java
+List<Object> values = redisTemplate.executePipelined((RedisCallback<Object>) connection -> {
+    for (String key : keys) {
+        connection.stringCommands().get(key.getBytes());
+    }
+    return null;
+});
+```
+
+---
+
+## 3. 异常处理反模式
+
+**铁律来源**：[rules §五](../../../../rules/code-dev-rules.md#五异常处理) + §八.3
+
+### 3.1 吞异常
+
+#### ❌ 反模式
+
+```java
+try {
+    remoteCall();
+} catch (Exception e) {
+    return Collections.emptyList();  // 平台故障被掩盖
+}
+```
+
+#### ✅ 正模式
+
+```java
+try {
+    return remoteCall();
+} catch (FeignException e) {
+    log.error("远程调用失败, service={}, reason={}", serviceName, e.getMessage());
+    throw new ServiceException("REMOTE_FAIL", "调用XX服务失败", e);
+}
+```
+
+**铁律 4 关联**：[data-boundary 反模式 §4](../meritdata-platform-data-boundary/references/anti-patterns.md#4-掩盖平台故障)
+
+### 3.2 空 catch 块
+
+#### ❌ 反模式
+
+```java
+try {
+    riskyOperation();
+} catch (Exception e) {
+    // 静默吞掉
+}
+```
+
+#### ✅ 正模式（必须三选一）
+
+```java
+// 选项 1：日志 + 上抛
+try { riskyOperation(); }
+catch (Exception e) { log.error("操作失败", e); throw new ServiceException(...); }
+
+// 选项 2：日志 + 显式降级（业务允许时）
+try { riskyOperation(); }
+catch (Exception e) { log.warn("操作降级", e); return defaultValue(); }
+
+// 选项 3：精确捕获（不要用 Exception）
+try { riskyOperation(); }
+catch (IllegalArgumentException e) { /* 业务校验失败，已知 */ }
+```
+
+### 3.3 finally 中抛异常
+
+#### ❌ 反模式
+
+```java
+try { conn = getConnection(); } 
+finally { conn.close(); }  // close() 抛异常会覆盖 try 中的异常
+```
+
+#### ✅ 正模式（try-with-resources）
+
+```java
+try (Connection conn = getConnection();
+     PreparedStatement ps = conn.prepareStatement(sql)) {
+    ps.execute();
+}  // 自动按相反顺序关闭，异常不被覆盖
+```
+
+---
+
+## 4. 敏感信息反模式
+
+**铁律来源**：[rules §六](../../../../rules/code-dev-rules.md#六敏感信息) + §八.3
+
+### 4.1 日志打印敏感字段
+
+#### ❌ 反模式
+
+```java
+log.info("user login: name={}, pwd={}", user.getName(), user.getPassword());
+log.debug("auth token: {}", token);
+log.info("principal: {}", SecurityContextHolder.getContext().getAuthentication());
+```
+
+#### ✅ 正模式
+
+```java
+log.info("user login: name={}, pwd=***", user.getName());
+// token / principal 严禁打印，如需调试用脱敏工具
+String maskedToken = SensitiveMasker.maskToken(token);  // 仅前4位+***
+```
+
+### 4.2 硬编码密钥
+
+#### ❌ 反模式
+
+```java
+private static final String SECRET_KEY = "abc123-meritdata-2024";
+private static final String DB_PASSWORD = "BigData.2018v6";
+```
+
+#### ✅ 正模式
+
+```java
+@Value("${app.crypto.sm4-key}")
+private String sm4Key;  // 从 Nacos 配置读取
+
+@NacosValue(value = "${db.password}", autoRefreshed = true)
+private String dbPassword;  // 加密配置项
+```
+
+**关联 skill**：`meritdata-platform-crypto-gm`、`meritdata-platform-config-item`
+
+### 4.3 异常信息泄露内部实现
+
+#### ❌ 反模式
+
+```java
+} catch (SQLException e) {
+    return Result.fail("SQL 错误: " + e.getMessage() + " 表: " + e.getSQLState());
+    // → 暴露表名、SQL 状态、数据库版本
+}
+```
+
+#### ✅ 正模式
+
+```java
+} catch (SQLException e) {
+    log.error("DB error, sqlState={}", e.getSQLState(), e);  // 详细日志内部保留
+    throw new ServiceException("DB_ERROR", "数据库操作失败");  // 用户只看到错误码
+}
+```
+
+---
+
+## 5. 架构层反模式
+
+**铁律来源**：[rules §八.3 架构层](../../../../rules/code-dev-rules.md#83-code-spec-补充铁律编码层) + §重要提醒
+
+### 5.1 Controller / Service / Dao 层有成员变量
+
+#### ❌ 反模式
+
+```java
+@Service
+public class OrderService {
+    private User currentUser;  // 多线程下数据错乱
+    private OrderContext context;  // 线程不安全
+}
+```
+
+#### ✅ 正模式
+
+```java
+@Service
+public class OrderService {
+    // 只有 @Autowired 注入的 final 依赖
+    private final OrderRepo orderRepo;
+    private final UserClient userClient;
+
+    public void createOrder(OrderDTO dto) {
+        User currentUser = SessionUtils.getCurrentUser();  // 每次从上下文取
+        // ...
+    }
+}
+```
+
+**理由**：Controller/Service/Dao 由 Spring 单例管理，多线程共享；非 final 成员变量会引发线程安全问题。
+
+### 5.2 Shell 脚本 Windows 换行符
+
+#### ❌ 反模式（CRLF，部署到 Linux 失败）
+
+```bash
+#!/bin/bash\r\n
+echo "starting..."\r\n
+```
+
+#### ✅ 正模式（LF）
+
+```bash
+#!/bin/bash
+echo "starting..."
+```
+
+**CI 校验**：
+
+```bash
+file scripts/*.sh | grep CRLF && echo "❌ 含 CRLF 换行符" && exit 1
+```
+
+### 5.3 平台特定：GridView 参数处理
+
+#### ❌ 反模式（手动拼 SQL）
+
+```java
+@GetMapping("/list")
+public List<OrderVO> list(@RequestParam Map<String, String> params) {
+    String sql = "SELECT * FROM t_order WHERE 1=1";
+    if (params.get("status") != null) {
+        sql += " AND status = '" + params.get("status") + "'";  // SQL 注入
+    }
+    // ...
+}
+```
+
+#### ✅ 正模式（GridView + QueryDSL）
+
+```java
+@GetMapping("/list")
+public GridView<OrderVO> list(GridQuery query, @RequestParam(required = false) String status) {
+    BooleanBuilder where = new BooleanBuilder();
+    if (status != null) where.and(qOrder.status.eq(status));
+    List<OrderVO> list = queryFactory
+        .select(Projections.bean(OrderVO.class, qOrder.all()))
+        .from(qOrder)
+        .where(where)
+        .offset(query.getOffset())
+        .limit(query.getLimit())
+        .fetch();
+    return new GridView<>(list, totalCount);
+}
+```
+
+---
+
+## 6. 平台特定规范
+
+### 6.1 ResultBody 响应包装
+
+#### ❌ 反模式
+
+```java
+@PostMapping("/create")
+public Order create(@RequestBody OrderDTO dto) {
+    return orderService.create(dto);  // 平台前端无法统一处理错误
+}
+```
+
+#### ✅ 正模式
+
+```java
+@PostMapping("/create")
+public ResultBody<OrderVO> create(@RequestBody OrderDTO dto) {
+    OrderVO vo = orderService.create(dto);
+    return ResultBody.success(vo);
+}
+```
+
+### 6.2 Swagger 注解
+
+#### ❌ 反模式（无注解）
+
+```java
+@GetMapping("/get")
+public UserVO get(Long id) { ... }  // Swagger 文档无字段说明
+```
+
+#### ✅ 正模式
+
+```java
+@ApiOperation("查询用户详情")
+@GetMapping("/get")
+public ResultBody<UserVO> get(
+    @ApiParam(value = "用户ID", required = true, example = "10001")
+    @RequestParam Long id
+) { ... }
+```
+
+### 6.3 二开业务表小写蛇形
+
+**铁律来源**：[rules §八.2](../../../../rules/code-dev-rules.md#82-业务建模规则domain-model) + §七
+
+#### ❌ 反模式（大写 / 驼峰）
+
+```sql
+CREATE TABLE PurchaseOrder (
+    orderNo VARCHAR(50),
+    createBy BIGINT,
+    createTime DATETIME
+);
+```
+
+#### ✅ 正模式（小写蛇形）
+
+```sql
+CREATE TABLE t_purchase_order (
+    order_no VARCHAR(50),
+    create_by BIGINT,
+    create_time DATETIME
+);
+```
+
+**实体类**（与表命名解耦）：
+
+```java
+@Entity
+@Table(name = "t_purchase_order")
+public class PurchaseOrder {
+    @Column(name = "order_no")
+    private String orderNo;
+
+    @Column(name = "create_by")
+    private Long createBy;
+}
+```
+
+---
+
+## 7. 速查表
+
+| 铁律 | 反模式关键特征 | 正模式关键特征 |
+|------|--------------|--------------|
+| 软删除唯一性 | `findByXxx` 校验唯一性 | `findXxxIncludingDeleted(nativeQuery)` |
+| 软删除编号生成 | `findAllXxxStartingWith` | `findAllXxxStartingWithIncludingDeleted(nativeQuery)` |
+| 循环不调外部 | `for + findById` | `findAllById + 内存 join` |
+| 循环不调 Feign | `for + userClient.getById` | `userClient.listByIds + 内存 join` |
+| 异常不吞 | `catch + return emptyList` | `throw new ServiceException` |
+| 异常 finally | `try/finally close()` | `try-with-resources` |
+| 敏感信息 | `log.info("pwd={}", pwd)` | `log.info("pwd=***")` |
+| 密钥硬编码 | `private static final SECRET = "..."` | `@NacosValue` 注入 |
+| Controller 成员变量 | `@Service private User u;` | `private final` 依赖 |
+| Shell 换行符 | CRLF | LF |
+| GridView | `Map<String,String>` 接参 | `GridQuery` 专用对象 |
+| ResultBody | `return entity` | `return ResultBody.success(entity)` |
+| 二开表命名 | `PurchaseOrder` | `t_purchase_order` |
+
+---
+
+## 8. 关联阅读
+
+- [validate-rules.md](validate-rules.md) — CI 自动化校验命令
+- [rules/code-dev-rules.md §八.3](../../../../rules/code-dev-rules.md#83-code-spec-补充铁律编码层) — 铁律摘要
+- [data-boundary anti-patterns](../meritdata-platform-data-boundary/references/anti-patterns.md) — 数据访问边界反模式
+- [domain-model anti-patterns](../meritdata-platform-domain-model/references/anti-patterns.md) — 业务建模反模式