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

package/skills/meritdata-platform-code-spec/references/validate-rules.md

@@ -1,321 +0,0 @@
-# CI 校验命令（code-spec）
-
-> **本文件与 [anti-patterns.md](anti-patterns.md) 一一对应**。每条铁律给出可在 CI 中直接执行的检测命令。**任一 🔴 阻断命令失败即拒绝合并**。
-
-## 使用方式
-
-```bash
-# 单 skill 校验
-bash tools/skill-vetter/run.sh code-spec
-
-# 或在 GitHub Actions 中：
-- name: code-spec validate
-  run: bash tools/skill-vetter/run.sh code-spec
-```
-
-## 全局配置
-
-```bash
-# 默认扫描 src/main/java 和 src/main/resources
-SRC="${SRC:-src/main/java}"
-RES="${RES:-src/main/resources}"
-EXIT=0
-
-check() {
-  local label="$1"
-  local cmd="$2"
-  local level="${3:-warn}"  # block | warn
-  echo "▶ $label [$level]"
-  if eval "$cmd"; then
-    echo "  ✅ pass"
-  else
-    echo "  ❌ FAIL"
-    if [ "$level" = "block" ]; then EXIT=1; fi
-  fi
-}
-```
-
----
-
-## 1. 软删除实体铁律（🔴 阻断）
-
-### 1.1 检测唯一性校验未穿透软删除
-
-```bash
-# 检测：业务代码用 findByXxx 做唯一性校验（受 @Where 过滤）
-check "唯一性校验穿透软删除" \
-  "! grep -rEn '@(SQLDelete|Where)' $SRC --include='*.java' -l | \
-       xargs grep -lE 'XxxNoDuplicateException|XxxExistsException' | \
-       xargs grep -E '@Query.*findBy[A-Z]' 2>/dev/null | \
-       grep -v 'IncludingDeleted'" \
-  block
-```
-
-**误报豁免**：在 grep 中加入 `grep -v '// ALLOW-soft-delete-bypass'` 跳过显式豁免行。
-
-### 1.2 检测编号生成器未穿透
-
-```bash
-check "编号生成器穿透软删除" \
-  "! grep -rEn 'XxxNoGenerator' $SRC --include='*.java' -l | \
-       xargs grep -E 'findAllNosStartingWith' 2>/dev/null | \
-       grep -v 'IncludingDeleted'" \
-  block
-```
-
-### 1.3 检测实体含 @SQLDelete 但缺 @Where
-
-```bash
-check "软删除实体缺 @Where" \
-  "! grep -rl '@SQLDelete' $SRC --include='*.java' | \
-       xargs grep -L '@Where(clause' 2>/dev/null" \
-  block
-```
-
----
-
-## 2. 循环与外部资源铁律（🔴 阻断）
-
-### 2.1 循环内调数据库
-
-```bash
-# 检测 for/while 循环内调 DAO 方法
-check "循环内调 DAO" \
-  "! grep -rEn '(for|while)\s*\(.*\)\s*\{' $SRC --include='*.java' -A 5 | \
-       grep -E '\.(findBy|findAll|findOne|save|delete|update)' | \
-       grep -E 'Repository|Dao|Mapper' | \
-       grep -v '// ALLOW-loop-db'" \
-  block
-```
-
-### 2.2 循环内调 Feign / HTTP
-
-```bash
-check "循环内调 Feign" \
-  "! grep -rEn '(for|while)\s*\(.*\)\s*\{' $SRC --include='*.java' -A 5 | \
-       grep -E '\.(getById|list|get|query|fetch|post)\(' | \
-       grep -E 'Client|Client\.|Feign' | \
-       grep -v '// ALLOW-loop-feign'" \
-  block
-```
-
-### 2.3 循环内调 Redis
-
-```bash
-check "循环内调 Redis" \
-  "! grep -rEn '(for|while)\s*\(.*\)\s*\{' $SRC --include='*.java' -A 5 | \
-       grep -E 'redisTemplate\.|RedisTemplate' | \
-       grep -v '// ALLOW-loop-redis'" \
-  block
-```
-
----
-
-## 3. 异常处理铁律（🔴 阻断）
-
-### 3.1 禁止空 catch 块
-
-```bash
-check "空 catch 块" \
-  "! grep -rEn 'catch\s*\([^)]+\)\s*\{\s*\}' $SRC --include='*.java'" \
-  block
-```
-
-### 3.2 禁止 catch 后仅 return emptyList
-
-```bash
-check "catch + return emptyList 吞异常" \
-  "! grep -rEn 'catch\s*\([^)]+\)\s*\{[^}]*return\s+Collections\.emptyList' $SRC --include='*.java'" \
-  block
-```
-
-### 3.3 禁止 finally 中调用 close()（应 try-with-resources）
-
-```bash
-check "finally 调 close 而非 try-with-resources" \
-  "! grep -rEn 'finally\s*\{[^}]*\.close\(\)' $SRC --include='*.java'" \
-  warn
-```
-
----
-
-## 4. 敏感信息铁律（🔴 阻断）
-
-### 4.1 禁止日志打印 password
-
-```bash
-check "日志打印 password" \
-  "! grep -rEn 'log\.(info|debug|warn|error).*\.?(password|getPassword|pwd)' $SRC --include='*.java' | \
-       grep -v '\\*\\*\\*\\|mask\\|// ALLOW-log-pwd'" \
-  block
-```
-
-### 4.2 禁止日志打印 token / keytab / principal
-
-```bash
-check "日志打印 token/keytab/principal" \
-  "! grep -rEn 'log\.(info|debug|warn|error).*\\b(token|keytab|principal)\\b' $SRC --include='*.java' | \
-       grep -v '// ALLOW-log-token'" \
-  block
-```
-
-### 4.3 禁止硬编码密钥
-
-```bash
-check "硬编码密钥" \
-  "! grep -rEn 'private\s+static\s+final\s+String\s+.*(SECRET|KEY|PASSWORD|TOKEN)\\s*=\\s*\"[^\"]{8,}\"' $SRC --include='*.java'" \
-  block
-```
-
----
-
-## 5. 架构层铁律（🔴 阻断 / ⚠️ 警告）
-
-### 5.1 Controller/Service/Dao 层禁止非 final 成员变量
-
-```bash
-# 检测 @Controller/@Service/@Repository/@Component 类内的非 final 字段
-check "Controller/Service/Dao 非 final 成员变量" \
-  "! grep -rEzn '@(Controller|Service|Repository|Component|RestController)' $SRC --include='*.java' | \
-       awk '/class\\s/{cls=NR; in_cls=1; has_anno=0} \
-            /@(Controller|Service|Repository|Component)/{has_anno=1} \
-            in_cls && /^\\s*(private|protected)\\s+[A-Z][^=;]*;/{ \
-              if (!/final/) print FILENAME\":\"NR\": \"$0; in_cls=0}'" \
-  block
-```
-
-**简化版**（仅 Service 层）：
-
-```bash
-check "Service 层非 final 成员变量" \
-  "! grep -rln '@Service' $SRC --include='*.java' | \
-       xargs grep -E '^\\s*(private|protected)\\s+[A-Z][a-zA-Z0-9]*\\s+[a-z][a-zA-Z0-9]*\\s*;' | \
-       grep -v 'final'" \
-  warn
-```
-
-### 5.2 Shell 脚本禁止 CRLF
-
-```bash
-check "Shell 脚本含 CRLF" \
-  "! file scripts/*.sh 2>/dev/null | grep -E 'CRLF|with CR'" \
-  block
-
-check "Shell 脚本 BOM" \
-  "! head -c 3 scripts/*.sh 2>/dev/null | grep -l $'\\xef\\xbb\\xbf'" \
-  warn
-```
-
----
-
-## 6. 平台特定规范（⚠️ 警告）
-
-### 6.1 Controller 缺 ResultBody 包装
-
-```bash
-check "Controller 返回值未包装 ResultBody" \
-  "! grep -rEn '@(Get|Post|Put|Delete)Mapping' $SRC --include='*.java' -A 3 | \
-       grep -E 'public\\s+[A-Z][a-zA-Z<>?, ]+\\s+[a-z][a-zA-Z]*\\s*\\(' | \
-       grep -v 'ResultBody<\\|void'" \
-  warn
-```
-
-### 6.2 缺 Swagger 注解
-
-```bash
-check "Controller 方法缺 @ApiOperation" \
-  "! grep -rEn '@(Get|Post|Put|Delete)Mapping' $SRC --include='*.java' -A 1 | \
-       grep -E 'public\\s' | \
-       grep -v '@ApiOperation'" \
-  warn
-```
-
-### 6.3 二开业务表未用小写蛇形
-
-```bash
-# 仅扫描 CREATE TABLE
-check "CREATE TABLE 大写/驼峰" \
-  "! grep -rEn 'CREATE TABLE [A-Z]' $RES 2>/dev/null" \
-  block
-```
-
----
-
-## 7. 完整 CI 脚本
-
-将以下内容保存为 `tools/skill-vetter/run.sh`：
-
-```bash
-#!/bin/bash
-set -e
-
-SKILL="${1:-all}"
-SRC="${SRC:-src/main/java}"
-RES="${RES:-src/main/resources}"
-EXIT=0
-
-check() {
-  local label="$1"
-  local pattern="$2"
-  local level="${3:-warn}"
-  echo "▶ [$level] $label"
-  if eval "$pattern" >/dev/null 2>&1; then
-    echo "  ✅ pass"
-  else
-    echo "  ❌ FAIL"
-    [ "$level" = "block" ] && EXIT=1
-  fi
-}
-
-if [ "$SKILL" = "code-spec" ] || [ "$SKILL" = "all" ]; then
-  echo "===== code-spec ====="
-  # 1. 软删除
-  check "1.1 唯一性校验穿透软删除" \
-    "! grep -rln '@SQLDelete' $SRC --include='*.java' | xargs grep -l 'XxxNoDuplicateException' 2>/dev/null | xargs grep 'findBy[A-Z]' 2>/dev/null | grep -v 'IncludingDeleted'" \
-    block
-
-  # 2. 循环
-  check "2.1 循环内调 DAO" \
-    "! grep -rEn '(for|while)\\s*\\(' $SRC --include='*.java' -A 5 | grep -E 'Repository|Dao' | grep '\\.\\(findBy\\|findAll\\|save\\|delete\\)'" \
-    block
-
-  # 3. 异常
-  check "3.1 空 catch" "! grep -rEn 'catch\\s*\\([^)]+\\)\\s*\\{\\s*\\}' $SRC --include='*.java'" block
-  check "3.2 catch + return emptyList" "! grep -rEn 'catch\\s*\\([^)]+\\)\\s*\\{[^}]*return\\s+Collections\\.emptyList' $SRC --include='*.java'" block
-
-  # 4. 敏感
-  check "4.1 日志打印 password" "! grep -rEn 'log\\.[a-z]+\\.[^)]*\\b(password|getPassword)\\b' $SRC --include='*.java' | grep -v '\\*\\*\\*'" block
-  check "4.3 硬编码密钥" "! grep -rEn 'private\\s+static\\s+final\\s+String\\s+(SECRET|KEY|PASSWORD|TOKEN)\\s*=' $SRC --include='*.java'" block
-
-  # 5. 架构
-  check "5.2 Shell CRLF" "! file scripts/*.sh 2>/dev/null | grep CRLF" block
-
-  # 6. 平台
-  check "6.3 CREATE TABLE 大写" "! grep -rEn 'CREATE TABLE [A-Z]' $RES 2>/dev/null" block
-fi
-
-exit $EXIT
-```
-
-## 8. 豁免机制
-
-```java
-// 行尾加 ALLOW-{rule} 注释跳过单行检测
-catch (Exception e) {
-    return Collections.emptyList(); // ALLOW-loop-feign  // 此行不报错
-}
-```
-
-CI 检测所有豁免并写入报告：
-
-```bash
-check "豁免清单" \
-  "grep -rEn 'ALLOW-[a-z-]+' $SRC --include='*.java' | sort -u" \
-  warn
-```
-
-## 9. 关联阅读
-
-- [anti-patterns.md](anti-patterns.md) — 反模式案例 + 正模式代码
-- [SKILL.md](../SKILL.md) — skill 顶层入口
-- [rules/code-dev-rules.md §八.3](../../../../rules/code-dev-rules.md#83-code-spec-补充铁律编码层) — 铁律摘要

package/skills/meritdata-platform-data-access/SKILL.md

@@ -1,131 +0,0 @@
----
-name: meritdata-platform-data-access
-description: |
-  数据访问统一入口（合并自 entities + services + integration）。覆盖二开代码访问"用户/组织/角色/字典/业务数据"的 4 种形态：同 JVM Service / 平台 Feign Client / 第三方 Feign / 复杂查询。
-  触发场景：需要拉平台人员/组织数据；要写 Feign Client；要批量装配业务数据 + 平台 DTO；要写复杂动态查询。
-  何时不用：纯业务表操作 → 用 domain-model；跨服务 JOIN / 复制平台 Entity → ❌ 禁止（用 data-boundary）。
-metadata:
-  version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-08"
-  risk: high
-  layer: L2
-  sub-layer: L2-C
-  stack: java
-allowed-tools: Read, Grep, Glob, Bash
----
-
-# 数据访问统一入口（data-access）
-
-> **合并自**：原 `entities` + `services` + `integration` 三个 skill。它们本质上是同一个问题——"二开代码如何访问外部数据"——只是按 JVM 部署形态拆开。
->
-> 本 skill 按 **4 步决策树**路由到对应 references。
-
-## 触发
-- 拉平台用户 / 组织 / 角色 / 字典数据
-- 写 Feign Client（平台 / 第三方）
-- 批量装配业务数据 + 平台 DTO（避免分页循环 Feign）
-- 构造复杂动态查询条件（QueryDSL）
-- 同步 HR / 短信 / 邮件 / 支付 / 物流
-- 接收外部系统推送（HR/ERP/LDAP 主数据入云）→ inbound 分支
-- **对外发布 WebApi 给外部系统**（供应商/银行/合作伙伴调用平台）🆕 v2.6.0
-
-## 不触发
-- 业务表设计 / 建模 → 用 `meritdata-platform-domain-model`
-- 跨服务 JOIN / 复制平台 Entity → ❌ **禁止**（详见 `meritdata-platform-data-boundary` 铁律）
-- 业务编码规范自查 → 用 `meritdata-platform-code-spec`
-- 业务附件（上传/下载/密级）→ 用 `meritdata-platform-file`（v2.5.0 新建）
-- 前端多服务 axios → 用 `meritdata-platform-frontend/references/http-client/`（v2.6.0 新建）
-
-## 前置约束
-- **禁止**分页循环逐条 Feign（详见 [rules/code-dev-rules.md §八.1](../../rules/code-dev-rules.md#81-数据访问边界data-boundary) 铁律 1.2）
-- **禁止** `catch + return emptyList` 掩盖 Feign 失败（铁律 1.4）
-- 即使同 JVM，仍**禁止**：直连平台数据库 / 复制平台 Entity / 跨库 JOIN
-- inbound 分支额外约束：批次号幂等（v2.5.0 合并自 masterdata-sync）
-
-## 路由（5 步决策树）
-
-### 第 1 步：判定部署形态
-
-**问题**：你的二开模块与平台模块部署在**同一个 JVM** 吗？
-
-- ✅ 是 → 看第 2 步 A
-- ❌ 否（独立部署 / 微服务）→ 看第 2 步 B
-
-判定方法 → [references/outbound/same-jvm-detection.md](references/outbound/same-jvm-detection.md)
-
-### 第 2 步 A：同 JVM 场景（outbound）
-
-直接注入平台 Service：
-
-| 需要的能力 | 参考 |
-|-----------|------|
-| 平台 Service 清单（IUserService/IOrgService/...）| [references/outbound/service-catalog.md](references/outbound/service-catalog.md) |
-| 典型用法 + 反模式 | [references/outbound/usage-patterns.md](references/outbound/usage-patterns.md) |
-
-### 第 2 步 B：跨 JVM / Feign 场景（outbound）
-
-通过 Feign Client 调平台：
-
-| 需要的知识 | 参考 |
-|-----------|------|
-| Feign Client 写法 + 超时/降级 | [references/outbound/feign-guide.md](references/outbound/feign-guide.md) |
-| **批量装配模式**（避免 N+1）| [references/outbound/batch-assembly.md](references/outbound/batch-assembly.md) |
-| 第三方接口（HR/短信/邮件/支付/物流）| [references/outbound/third-party.md](references/outbound/third-party.md) |
-
-### 第 3 步：DTO 转换（outbound）
-
-无论同 JVM 还是 Feign，业务 VO 都需要从平台 DTO 装配：
-
-| 需要的知识 | 参考 |
-|-----------|------|
-| 平台 DTO 清单（UserDTO/OrgDTO/...）| [references/outbound/dto-catalog.md](references/outbound/dto-catalog.md) |
-| DTO ↔ VO 转换工具（MapStruct）| [references/outbound/dto-converter.md](references/outbound/dto-converter.md) |
-| QueryDSL Q 类查询 | [references/outbound/querydsl-guide.md](references/outbound/querydsl-guide.md) |
-
-### 第 4 步：外部系统推送到平台（inbound）🆕
-
-> **v2.5.0 合并自** `meritdata-platform-masterdata-sync`（研发 + 石油 22-modules）
-> **方向相反**：外部系统（HR/ERP/LDAP）主动推送数据到平台，与 outbound 是镜像关系
-
-| 需要的知识 | 参考 |
-|-----------|------|
-| REST / WebService 通道选型 | [references/inbound/sync-contracts.md](references/inbound/sync-contracts.md) |
-| Canonical Payload 设计（业务键/水位/批次号）| [references/inbound/canonical-payload.md](references/inbound/canonical-payload.md) |
-| 适配层模式（来源 DTO → canonical → 平台）| [references/inbound/adapter-pattern.md](references/inbound/adapter-pattern.md) |
-| 同步后对账（4 维度 + 处置）| [references/inbound/reconciliation.md](references/inbound/reconciliation.md) |
-| XML 安全（XXE / DTD / SOAPAction）| [references/inbound/xml-security.md](references/inbound/xml-security.md) |
-
-**inbound 关键提醒**：
-- 同步顺序：组织 → 角色/职务 → 人员 → 资源 → 授权（违反 → 孤儿数据）
-- 必须对账：HTTP 200 不算成功，要 4 维度对账
-- 全量替换强制审批（避免误删）
-- 批次号全局唯一 + 可重放
-
-### 第 5 步：对外发布 WebApi（外部系统调平台）🆕 v2.6.0
-
-> **方向不同** — 与 outbound（平台调外部）相反：这里是外部系统调平台，路径 `/webapi/**`，用 App-Key + App-Token 认证。
-
-| 需要的知识 | 参考 |
-|-----------|------|
-| 调用方向判定（外部 vs 同集群 vs 同 JVM）| [references/outbound/webapi.md](references/outbound/webapi.md#一调用方向判定首要) |
-| 接口编目 5 要素 + App 注册授权 | [references/outbound/webapi.md](references/outbound/webapi.md#三接口编目5要素) |
-| 错误码 431-437 + 生成规则 | [references/outbound/webapi.md](references/outbound/webapi.md#五错误码431-437-认证类-业务-resultbody) |
-| WA-01 ~ WA-07 验收清单 | [references/outbound/webapi.md](references/outbound/webapi.md#九wa-01--wa-07-验收清单) |
-
-**WebApi 关键提醒**：
-- 路径必须 `/webapi/**`（不是 `/api/open/**` / `/external/**`）
-- 必须先 WebApiInfo 登记 + AppAuth 授权（最小 API 集）
-- 写接口必须有幂等键（防重放）
-- appSecret 不进日志 / 异常 / 响应（详见 security-rules.md）
-
----
-
-## 关键提醒
-
-- **跨服务 JOIN / 复制平台 Entity / 直连平台 DB** → 永远禁止（违反铁律，走 data-boundary）
-- **同 JVM 也走 Feign** 的场景：部分模块同 JVM + 部分模块独立时，建议统一走 Feign（fallback 走本地）→ 见 [same-jvm-detection.md §5](references/outbound/same-jvm-detection.md#5-灰度场景部分同-jvm)
-- **批量装配是默认**而非可选：列表页必走批量 Feign + 内存 join
-- **inbound 与 outbound 是镜像**：方向相反但同属"跨系统数据流"，决策树可分别走两边

package/skills/meritdata-platform-data-access/references/datasource.md

@@ -1,239 +0,0 @@
-# 数据源管理（datasource）
-
-> **目的**：覆盖二开代码访问**业务库数据源**的 3 类能力。
-> **来源**：研发版 `meritdata-cloud-dev/modules/merit-cloud-datasource/` 整合（v2.2.0 P1 补齐）。
-> **范围**：仅业务库数据源；平台库由平台自身管理，不在本文范围。
-
----
-
-## 一、3 类能力
-
-| 能力 | 触发关键词 | 主要用途 |
-|------|---------|---------|
-| **元数据查询** | schema / table / column / 数据源连通性 | 动态建表、字段反射、字段校验 |
-| **动态连接池** | 多数据源 / 动态切换 / 运行时新增 | 跨库查询、读写分离、外部数据源接入 |
-| **安全 SQL** | PreparedStatement / 参数化 / SQL 注入防护 | 高风险 SQL 执行场景 |
-
----
-
-## 二、数据源元数据（metadata）
-
-### 2.1 用途
-
-二开代码需要在运行时检查/构建 SQL 时，必须能查询数据源的元数据：
-
-```java
-// 场景：动态校验实体字段是否存在于表
-boolean columnExists(String tableName, String columnName);
-
-// 场景：根据用户配置动态构建查询条件
-List<String> getTableColumns(String tableName);
-```
-
-### 2.2 平台支持
-
-平台提供 `IDatasourceMetadataService`（同 JVM）或 Feign Client（跨 JVM），含 8 个方法：
-
-| 方法 | 用途 | 返回 |
-|------|------|------|
-| `testConnection(dataSourceId)` | 测试连通性 | `boolean` |
-| `listSchemas(dataSourceId)` | 列出 schema | `List<String>` |
-| `listTables(schema)` | 列出表 | `List<TableInfo>` |
-| `listColumns(tableName)` | 列出字段 | `List<ColumnInfo>` |
-| `getTableInfo(tableName)` | 单表详情 | `TableInfo` |
-| `getPrimaryKeys(tableName)` | 主键信息 | `List<String>` |
-| `getIndexes(tableName)` | 索引信息 | `List<IndexInfo>` |
-| `getDatabaseVersion()` | 数据库版本 | `String` |
-
-### 2.3 二开使用约束
-
-| ✅ 允许 | ❌ 禁止 |
-|--------|--------|
-| 查询业务库的表/字段信息 | 查**平台库**的 `PF_*` 表（违反 data-boundary 铁律 1.1）|
-| 用于动态 SQL 构建 | 用于绕过 `@SQLDelete` 软删除（违反 data-boundary §四）|
-| 用于字段校验 | 查**其他业务服务**的表（跨服务应走 Feign，违反 §2.2）|
-
-### 2.4 平台表清单豁免
-
-> **重要**：`datasource.metadata` **不豁免** data-boundary 铁律 1.1。
-> 二开库查 `PF_*` 表 → 仍然禁止，即使通过元数据 API。
-
----
-
-## 三、动态连接池（dynamic-pool）
-
-### 3.1 用途
-
-二开需要运行时新增/切换数据源：
-
-| 场景 | 例子 |
-|------|------|
-| 跨库查询 | 业务库 A + 业务库 B 同查（注意：仅限二开库之间）|
-| 外部数据源 | 接入客户提供的只读数据源 |
-| 读写分离 | 主库写入，从库查询 |
-
-### 3.2 平台提供的能力
-
-平台提供 `IDynamicDatasourceManager` 含 5 个方法：
-
-| 方法 | 用途 | 注意事项 |
-|------|------|---------|
-| `register(dataSourceConfig)` | 运行时注册新数据源 | 仅业务库；平台库禁用 |
-| `deregister(dataSourceId)` | 注销数据源 | 应用关闭时清理 |
-| `switchTo(dataSourceId)` | 切换当前线程数据源 | 用 `try-finally` 恢复 |
-| `getCurrentDataSourceId()` | 当前线程数据源 ID | 用于日志/审计 |
-| `getAllDataSourceIds()` | 列出所有数据源 | 含业务库 + 外部 |
-
-### 3.3 标准用法（ThreadLocal 切换）
-
-```java
-// ✅ 正模式：try-finally 保证恢复
-@AutoLog(type = LogType.SERVICE)
-public List<OrderVO> queryAcrossDatabases(String orderNo) {
-    dynamicDatasourceManager.switchTo("DATA_SOURCE_B");
-    try {
-        return orderRepository.findByOrderNo(orderNo);
-    } finally {
-        dynamicDatasourceManager.switchTo("DEFAULT");  // 必恢复
-    }
-}
-```
-
-### 3.4 反模式（❌ 禁止）
-
-```java
-// ❌ 反模式 1：忘记恢复，导致后续 SQL 走错数据源
-dynamicDatasourceManager.switchTo("DATA_SOURCE_B");
-return orderRepository.findByOrderNo(orderNo);  // 漏 finally
-
-// ❌ 反模式 2：在循环内切换（性能 + 风险）
-for (String id : ids) {
-    dynamicDatasourceManager.switchTo(id);
-    processOne(id);  // 每次切换都走 ThreadLocal，O(N) 次切换
-}
-
-// ❌ 反模式 3：切换到平台库
-dynamicDatasourceManager.switchTo("PF_DATA_SOURCE");  // 违反铁律 1.1
-```
-
-### 3.5 铁律约束
-
-| 铁律 | 来源 |
-|------|------|
-| 禁止切换到平台库 | `meritdata-platform-data-boundary.md §1.1` |
-| 动态注册后必须清理 | `meritdata-platform-code-spec` §资源管理 |
-| 跨库 JOIN 仍然禁止（动态连接池不等于跨库 JOIN）| `meritdata-platform-data-boundary.md §1.1` |
-
----
-
-## 四、安全 SQL（safe-sql）
-
-### 4.1 用途
-
-当二开代码必须**直接拼接/执行 SQL** 时（如动态建表、复杂报表），必须使用安全 SQL 模式：
-
-| 风险 | 场景 |
-|------|------|
-| **SQL 注入** | 拼接用户输入到 SQL（违反 security-rules.md §一）|
-| **错误转义** | like 过滤未处理 `_%`（违反 code-dev-rules.md §二）|
-| **DDL 误执行** | 动态 DROP/ALTER 影响生产 |
-
-### 4.2 平台提供的能力
-
-平台提供 `ISafeSqlExecutor` 含 4 个方法：
-
-| 方法 | 用途 | 返回 |
-|------|------|------|
-| `executeSelect(sql, params, rowMapper)` | 参数化 SELECT | `List<T>` |
-| `executeUpdate(sql, params)` | 参数化 INSERT/UPDATE/DELETE | `int`（影响行数）|
-| `executeDdl(ddl)` | 受控 DDL（仅允许 CREATE/ALTER）| `void` |
-| `escapeLikePattern(pattern)` | like 过滤特殊字符转义 | `String` |
-
-### 4.3 标准用法（PreparedStatement）
-
-```java
-// ✅ 正模式：PreparedStatement + 参数化
-String sql = "SELECT * FROM t_order WHERE order_no = ? AND create_by LIKE ? ESCAPE '/'";
-List<OrderVO> orders = safeSqlExecutor.executeSelect(
-    sql,
-    List.of(orderNo, escapeLikePattern(userInput) + "%"),
-    OrderVO.class
-);
-
-// ✅ 正模式：动态 IN 条件
-List<Long> ids = List.of(1L, 2L, 3L);
-String placeholders = ids.stream().map(i -> "?").collect(Collectors.joining(","));
-String sql = "SELECT * FROM t_order WHERE id IN (" + placeholders + ")";
-List<OrderVO> orders = safeSqlExecutor.executeSelect(sql, ids, OrderVO.class);
-```
-
-### 4.4 反模式（❌ 禁止）
-
-```java
-// ❌ 反模式 1：字符串拼接用户输入
-String sql = "SELECT * FROM t_order WHERE order_no = '" + orderNo + "'";  // SQL 注入
-
-// ❌ 反模式 2：like 过滤未处理特殊字符
-String sql = "SELECT * FROM t_user WHERE name LIKE '%" + input + "%'";  // %/_ 通配符逃逸
-
-// ❌ 反模式 3：DROP 在生产环境执行
-safeSqlExecutor.executeDdl("DROP TABLE t_temp_data");  // 必须审计 + 二次确认
-
-// ❌ 反模式 4：循环内单条执行（性能）
-for (String no : orderNos) {
-    safeSqlExecutor.executeUpdate("UPDATE t_order SET status = ? WHERE no = ?", 
-                                   List.of("PAID", no));  // 应该用批量
-}
-```
-
-### 4.5 批量插入（必须用批量）
-
-```java
-// ✅ 正模式：批量执行（一次 SQL 往返）
-List<Object[]> params = orderNos.stream()
-    .map(no -> new Object[]{"PAID", no})
-    .collect(Collectors.toList());
-int affected = safeSqlExecutor.executeBatchUpdate(
-    "UPDATE t_order SET status = ? WHERE no = ?",
-    params
-);
-```
-
-性能差异：
-- 单条循环 1000 条 = 1000 次 SQL 往返 = ~3 秒
-- 批量 1000 条 = 1 次 SQL 往返 = ~0.05 秒
-
----
-
-## 五、与其他 skill 的协作
-
-| 场景 | 涉及 skill |
-|------|----------|
-| 动态 SQL 涉及人员/组织过滤 | `meritdata-platform-org-user-api`（先批量拉，再内存 join）|
-| 数据源元数据 + 动态建表 | `meritdata-platform-impexp`（导入模板动态生成）|
-| 跨服务数据源接入 | `meritdata-platform-data-access`（跨服务走 Feign，不直连）|
-| SQL 涉及敏感数据 | `meritdata-platform-data-classification`（数据密级 + Hibernate Filter）|
-
----
-
-## 六、性能与监控
-
-| 关注点 | 建议 |
-|--------|------|
-| 动态数据源切换频率 | 监控 ThreadLocal 切换次数；O(>100/秒) 需重构 |
-| SQL 执行时间 | > 500ms 必须查执行计划（`explain`）|
-| DDL 执行 | 必须记录到操作日志（`@AutoLog(type = LogType.DDL)`）|
-| 连接泄漏 | 监控 `getConnection()` vs `close()` 配对 |
-
----
-
-## 七、相关资源
-
-| 资源 | 路径 |
-|------|------|
-| data-boundary 铁律 | `meritdata-platform-suite/rules/meritdata-platform-data-boundary.md §1.1` |
-| code-spec 资源管理 | `meritdata-platform-suite/skills/meritdata-platform-code-spec/SKILL.md` |
-| security-rules 注入防护 | `meritdata-platform-suite/rules/security-rules.md §一` |
-| data-classification 密级 | `meritdata-platform-suite/skills/meritdata-platform-data-classification/SKILL.md` |
-| 22 modules 来源 | `meritdata-platform-suite/skills/meritdata-platform-cloud-dev/references/modules-mapping.md §模块 10: merit-cloud-datasource` |
-| 研发版源 | `研发skills/skills/meritdata-cloud-dev/modules/merit-cloud-datasource/module.md` |