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

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

@@ -0,0 +1,321 @@
+# 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

@@ -0,0 +1,131 @@
+---
+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

@@ -0,0 +1,239 @@
+# 数据源管理（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` |