@alanwang-merit/meritdata-platform-skill-package 1.0.8 → 1.0.10

package/skills/meritdata-platform-bootstrap-2nd-dev/scripts/bootstrap.sh

@@ -0,0 +1,350 @@
+#!/usr/bin/env bash
+#
+# bootstrap.sh - 自包含新二开项目生成脚本（macOS / Linux / Git Bash）
+#
+# 用法：
+#   bootstrap.sh <项目名> [目标目录] [包名] [Nacos profile]
+#
+# 参数：
+#   <项目名>        必填，英文项目名（用于 back-end 工件名 + front-end 页面目录 + 包名）
+#   [目标目录]      可选，默认 <repo>/generated-projects/<项目名>/
+#   [包名]          可选，默认 com.meritdata.cloud.<项目名>
+#   [Nacos profile] 可选，默认 common-<项目名>
+#
+# 退出码：
+#   0  成功
+#   1  参数错误
+#   2  bundled 目录缺失
+#   3  目标目录已存在（避免覆盖）
+#
+# 示例：
+#   bootstrap.sh contract
+#   bootstrap.sh hr ./my-hr com.meritdata.cloud.hr common-hr
+#
+# 注意：
+#   1. 本脚本只读取 bundled/ 下的模板，不修改任何现有工程目录
+#   2. 占位符替换仅针对 bundled/ 后端模板 和 bundled/ 前端模板/yourapp/ 路径
+#   3. 不会触碰任何 .claude/skills/ 或 .agents/skills/ 文件
+#   4. 不会创建 Git 仓库（自行 git init）
+
+set -euo pipefail
+
+# =========================
+# 0. 参数解析与校验
+# =========================
+if [ $# -lt 1 ] || [ $# -gt 4 ]; then
+    echo "用法: $0 <项目名> [目标目录] [包名] [Nacos profile]"
+    echo ""
+    echo "参数："
+    echo "  <项目名>        必填，英文项目名"
+    echo "  [目标目录]      可选，默认 <repo>/generated-projects/<项目名>/"
+    echo "  [包名]          可选，默认 com.meritdata.cloud.<项目名>"
+    echo "  [Nacos profile] 可选，默认 common-<项目名>"
+    exit 1
+fi
+
+PROJECT_NAME="$1"
+
+# 计算路径：脚本位于 .claude/skills/meritdata-platform-bootstrap-2nd-dev/scripts/
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(dirname "$SCRIPT_DIR")"
+BUNDLED_DIR="$SKILL_DIR/bundled"
+
+# 解析 skill 所在 repo 的根目录（向上三级 .claude/skills/meritdata-platform-bootstrap-2nd-dev）
+REPO_ROOT="$(cd "$SKILL_DIR/../../.." && pwd)"
+DEFAULT_TARGET="$REPO_ROOT/generated-projects/$PROJECT_NAME"
+TARGET_DIR="${2:-$DEFAULT_TARGET}"
+PACKAGE_NAME="${3:-com.meritdata.cloud.$PROJECT_NAME}"
+NACOS_PROFILE="${4:-common-$PROJECT_NAME}"
+
+# bundled 校验
+if [ ! -d "$BUNDLED_DIR" ]; then
+    echo "[ERROR] bundled 目录不存在：$BUNDLED_DIR" >&2
+    exit 2
+fi
+
+# 目标目录冲突校验
+if [ -e "$TARGET_DIR" ]; then
+    echo "[ERROR] 目标目录已存在：$TARGET_DIR" >&2
+    echo "        如需重新生成，请先删除或换一个新项目名" >&2
+    exit 3
+fi
+
+# 包名基本格式校验（Java 包名规范：字母开头，含 . 数字字母下划线）
+if [[ ! "$PACKAGE_NAME" =~ ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$ ]]; then
+    echo "[ERROR] 包名格式不合法：$PACKAGE_NAME" >&2
+    echo "        应符合 Java 包名规范（如 com.meritdata.cloud.contract）" >&2
+    exit 1
+fi
+
+# 项目名校验（英文 + 中划线下划线）
+if [[ ! "$PROJECT_NAME" =~ ^[a-z][a-z0-9_-]*$ ]]; then
+    echo "[ERROR] 项目名格式不合法：$PROJECT_NAME" >&2
+    echo "        应以小写字母开头，仅含字母/数字/中划线/下划线（如 contract / hr-system）" >&2
+    exit 1
+fi
+
+# =========================
+# 1. 创建目标目录结构
+# =========================
+# 在目标目录创建后端源码结构
+mkdir -p "$TARGET_DIR/后端/src/main/java/$(echo "$PACKAGE_NAME" | tr '.' '/')"
+mkdir -p "$TARGET_DIR/后端/src/main/resources"
+mkdir -p "$TARGET_DIR/后端/src/test/java"
+mkdir -p "$TARGET_DIR/后端/src/main/java/com/meritdata/cloud/common"
+mkdir -p "$TARGET_DIR/前端/src/pages/$PROJECT_NAME"
+
+echo "[INFO] 生成项目：$PROJECT_NAME"
+echo "[INFO] 目标目录：$TARGET_DIR"
+echo "[INFO] 包名    ：$PACKAGE_NAME"
+echo "[INFO] Nacos   ：$NACOS_PROFILE"
+echo ""
+
+# =========================
+# 2. 模板变量准备
+# =========================
+NOW="$(date '+%Y-%m-%d %H:%M:%S')"
+# 应用类名：项目名转 PascalCase（contract → Contract, hr-system → HrSystem）
+APP_CLASS_NAME="$(echo "$PROJECT_NAME" | sed -E 's/(^|[-_])([a-z])/\U\2/g')"
+MERIT_CLOUD_VERSION="6.13.2"
+PROJECT_VERSION="0.0.1-SNAPSHOT"
+PROJECT_DESC="二开样例项目 - $PROJECT_NAME"
+AUTHOR="maohan"
+PORT="18080"
+CLOUD_HOME="D:/A_meritdata/Env_windows_V6.13.2"
+APP_NAME="$PROJECT_NAME"
+
+# =========================
+# 3. 后端：处理 bundled/后端模板/*.vm 模板（4 个文件）
+# =========================
+echo "[STEP] 处理 back-end 模板"
+
+for vm_file in "$BUNDLED_DIR/后端模板/"*.vm; do
+    [ -e "$vm_file" ] || continue
+    filename="$(basename "$vm_file" .vm)"
+
+    # 根据模板文件名决定目标位置（同时去 .vm 后缀 + 替换 Velocity 占位符）
+    case "$filename" in
+        application.java)
+            target_file="$TARGET_DIR/back-end/src/main/java/$(echo "$PACKAGE_NAME" | tr '.' '/')/${APP_CLASS_NAME}Application.java"
+            ;;
+        pom.xml)
+            target_file="$TARGET_DIR/back-end/pom.xml"
+            ;;
+        bootstrap.properties)
+            target_file="$TARGET_DIR/back-end/src/main/resources/bootstrap.properties"
+            ;;
+        banner.txt)
+            target_file="$TARGET_DIR/back-end/src/main/resources/banner.txt"
+            ;;
+        *)
+            target_file="$TARGET_DIR/back-end/$filename"
+            ;;
+    esac
+
+    mkdir -p "$(dirname "$target_file")"
+
+    # Velocity 占位符替换（每个 token 独立 sed 表达式，避免贪婪）
+    sed \
+        -e "s|\$!callback\.setFileName([^)]*)||g" \
+        -e "s|\$!callback\.setSavePath([^)]*)||g" \
+        -e "s|\$!{projectInfo\.appCode}|$APP_NAME|g" \
+        -e "s|\$!{projectInfo\.packageName}|$PACKAGE_NAME|g" \
+        -e "s|\$!{projectInfo\.meritCloudVersion}|$MERIT_CLOUD_VERSION|g" \
+        -e "s|\$!{projectInfo\.port}|$PORT|g" \
+        -e "s|\$!{projectInfo\.cloudHome}|$CLOUD_HOME|g" \
+        -e "s|\$!{projectInfo\.version}|$PROJECT_VERSION|g" \
+        -e "s|\$!{projectInfo\.desc}|$PROJECT_DESC|g" \
+        -e "s|\$!{author}|$AUTHOR|g" \
+        -e "s|\$!{time\.currTime()}|$NOW|g" \
+        -e '/^[[:space:]]*$/N;/^\n$/D' \
+        "$vm_file" > "$target_file"
+
+    echo "  [OK] $filename -> $(realpath --relative-to="$TARGET_DIR" "$target_file" 2>/dev/null || echo "$target_file")"
+done
+
+# =========================
+# 4. 后端：处理 back-end-common 通用代码（25 文件）
+# =========================
+echo "[STEP] 处理 back-end-common 通用代码"
+
+if [ -d "$BUNDLED_DIR/back-end-common/common" ]; then
+    # 递归复制 common/ 下所有内容（含子目录 entity/ + imp/）
+    if command -v rsync >/dev/null 2>&1; then
+        rsync -a "$BUNDLED_DIR/back-end-common/common/" "$TARGET_DIR/back-end/src/main/java/com/meritdata/cloud/common/"
+    else
+        cp -r "$BUNDLED_DIR/back-end-common/common/." "$TARGET_DIR/back-end/src/main/java/com/meritdata/cloud/common/"
+    fi
+    file_count=$(find "$TARGET_DIR/back-end/src/main/java/com/meritdata/cloud/common/" -type f | wc -l)
+    echo "  [OK] 通用代码已复制（$file_count 个文件）"
+else
+    echo "  [WARN] bundled/back-end-common/common 目录不存在，跳过"
+fi
+
+# =========================
+# 5. 前端：处理 bundled/前端模板/yourapp 路径（12 文件）
+# =========================
+echo "[STEP] 处理 front-end 模板"
+
+if [ -d "$BUNDLED_DIR/前端模板/yourapp" ]; then
+    # 遍历 yourapp 下所有文件/目录
+    while IFS= read -r -d '' src_file; do
+        rel_path="${src_file#$BUNDLED_DIR/前端模板/yourapp/}"
+        target_file="$TARGET_DIR/front-end/src/pages/$PROJECT_NAME/$rel_path"
+
+        if [ -d "$src_file" ]; then
+            mkdir -p "$target_file"
+        else
+            mkdir -p "$(dirname "$target_file")"
+            # 前端替换：将字面量 "yourapp" 与 "/api/yourapp" 替换为项目名
+            # 注意：只替换业务路径前缀，不替换组件名（如 cloud-module-base 路径）
+            sed \
+                -e "s|/api/yourapp|/api/$PROJECT_NAME|g" \
+                -e "s|\"yourapp\"|\"$PROJECT_NAME\"|g" \
+                "$src_file" > "$target_file"
+        fi
+    done < <(find "$BUNDLED_DIR/前端模板/yourapp" -mindepth 1 -print0)
+
+    file_count=$(find "$TARGET_DIR/front-end/src/pages/$PROJECT_NAME/" -type f | wc -l)
+    echo "  [OK] front-end 页面已生成到 src/pages/$PROJECT_NAME/（$file_count 个文件）"
+else
+    echo "  [WARN] bundled/front-end/yourapp 目录不存在，跳过"
+fi
+
+# =========================
+# 6. 生成 README.md
+# =========================
+cat > "$TARGET_DIR/README.md" <<EOF
+# $PROJECT_NAME
+
+> 二开样例项目 - 由 \`meritdata-platform-bootstrap-2nd-dev\` skill 生成于 $NOW
+
+## 项目信息
+
+| 项 | 值 |
+|----|-----|
+| 项目名 | \`$PROJECT_NAME\` |
+| 包名 | \`$PACKAGE_NAME\` |
+| 启动类 | \`${APP_CLASS_NAME}Application\` |
+| Nacos profile | \`$NACOS_PROFILE\` |
+| 平台版本 | $MERIT_CLOUD_VERSION |
+| 生成时间 | $NOW |
+
+## 目录结构
+
+\`\`\`
+$PROJECT_NAME/
+├── README.md
+├── .gitignore
+├── 后端目录/                                       # 后端工程（Maven war / JDK 21）
+│   ├── pom.xml
+│   └── src/main/
+│       ├── java/$(echo "$PACKAGE_NAME" | tr '.' '/')/${APP_CLASS_NAME}Application.java
+│       ├── java/com/meritdata/cloud/common/        # 平台通用代码（导入导出 + BPM DTO + Feign）
+│       └── resources/bootstrap.properties          # Nacos 配置入口
+└── 前端目录/                                      # 前端工程（Vue 2 + Element UI）
+    └── src/pages/$PROJECT_NAME/                    # 业务页面（10+ 文件）
+\`\`\`
+
+## 下一步
+
+### 1. Nacos 配置
+
+在 Nacos 控制台创建配置：
+- **Data ID**: \`$NACOS_PROFILE.properties\`
+- **Group**: \`DEFAULT_GROUP\`
+- **Namespace**: \`public\`
+- **配置内容**: 参考现有 \`common-platform-demo.properties\` 或 \`common-cloud-system-manage.properties\`
+
+### 2. 启动后端
+
+\`\`\`bash
+cd back-end
+mvn clean compile
+mvn spring-boot:run
+# 访问 http://localhost:$PORT/actuator/health
+\`\`\`
+
+### 3. 启动前端
+
+\`\`\`bash
+cd front-end
+npm install --legacy-peer-deps
+npm run serve
+# 访问 http://localhost:8083/$PROJECT_NAME/
+\`\`\`
+
+### 4. 添加业务模块
+
+使用 \`meritdata-platform-cloud-dev\` skill 生成业务代码：
+
+> "我要在 $PROJECT_NAME 项目里加一个合同管理模块"
+
+## 相关 Skill
+
+| Skill | 用途 |
+|-------|------|
+| \`meritdata-platform-cloud-dev\` | 生成业务模块代码 |
+| \`meritdata-platform-playbook\` | 整体开发流程编排 |
+| \`meritdata-platform-2nd-dev-check\` | 二开就绪度检查 |
+| \`meritdata-nacos-importer\` | 批量导入 Nacos 配置 |
+| \`meritdata-platform-menu-config\` | 挂载菜单到 cloud-system-manage |
+EOF
+
+echo "  [OK] README.md"
+
+# =========================
+# 7. 生成 .gitignore
+# =========================
+cat > "$TARGET_DIR/.gitignore" <<EOF
+# IDE
+.idea/
+*.iml
+.vscode/
+.settings/
+.project
+.classpath
+.factorypath
+
+# Java/Maven
+target/
+*.class
+*.jar
+*.war
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build output
+dist/
+build/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+logs/
+*.log
+EOF
+
+echo "  [OK] .gitignore"
+
+# =========================
+# 8. 完成
+# =========================
+echo ""
+echo "=========================================="
+echo "[OK] 项目生成完成"
+echo "    路径：$TARGET_DIR"
+echo "=========================================="
+echo ""
+echo "后续步骤："
+echo "  1. cd \"$TARGET_DIR\""
+echo "  2. 在 Nacos 创建 common-$NACOS_PROFILE.properties"
+echo "  3. cd back-end && mvn spring-boot:run"
+echo "  4. cd front-end && npm install --legacy-peer-deps && npm run serve"
+echo ""

package/skills/meritdata-platform-bpm/SKILL.md

@@ -1,39 +1,103 @@
 ---
 name: meritdata-platform-bpm
-description: |
-  流程引擎（BPM）接入。设计审批流 BPMN 图、配置节点/网关/条件、把流程实例 ID 接入业务表、监听回调、流程状态变更。
-  触发场景：业务模块需要加审批流；流程图调整；流程回调处理。
-  何时不用：纯业务状态管理（无审批）→ 用 domain-model；流程已建好只调 API → 用 entities。
+description: 美林开发平台或 MeritData 二开中的 BPM 工作流。仅仅当需求明确涉及平台 BPM、BpmEngine、流程定义、待办、动态处理人、流程追踪、Portal 待办同步或 BPM 前端组件时使用；普通审批业务不触发。
 metadata:
-  version: "1.0.0"
-  author: petroleum+rd
-  source: petroleum+rd
-  date_added: "2026-09-07"
-  last_modified: "2026-09-07"
-  risk: medium
-  layer: L2
-  sub-layer: L2-C
-  stack: java
-allowed-tools: Read, Grep, Glob, Bash
+  version: "1.2.0"
+  author: 技术平台部门架构组
+  source: company
+  date_added: "2026-09-01"
+  last_updated: "2026-09-02"
+  risk: low
+  allowed-tools: Read, Grep, Glob
 ---
 
-# 流程引擎（BPM）
+## ⭐ MUST DO
 
-## 触发
-- 新业务模块需要加审批流（BPMN）
-- 已有流程图调整节点/条件/审批人
-- 流程回调/状态变更需要写入业务表
-- 流程与业务状态字段同步问题
+**对 BPM 工作流场景，先确认目标版本和已部署接口，再读 references 中的 api-reference.md，避免凭历史示例推断接口签名。**
 
-## 不触发
-- 业务表设计/聚合根 → 用 `meritdata-platform-domain-model`
-- 业务编码规范自查 → 用 `meritdata-platform-code-spec`
-- 平台 Flowable/Camunda API 直接调用（已知方法名）→ 用 `meritdata-platform-entities`
+## 触发条件 / 不适用
 
-## 前置约束
-- 业务状态字段与流程实例 ID **必须分离**（详见 [rules/code-dev-rules.md §八.2](../../rules/code-dev-rules.md#82-业务建模规则domain-model)）
-- 流程状态变更走平台公共方法，不直接 UPDATE 业务表 status
+**适用**：
+- 流程定义、发起、审批、退回、撤回、待办、阅知和流程追踪
+- BPM 表单/列表组件、监听表达式、动态处理人和门户待办同步
 
-## 路由
-- BPMN 设计要点 + 节点类型 → [references/guide.md](references/guide.md)
-- 与 domain-model 字段对应关系 → [references/status-mapping.md](references/status-mapping.md)
+**不适用**：
+- 普通实体查询 → `meritdata-platform-entities`
+- 通用前端组件 → `meritdata-platform-frontend`
+- 平台开放接口 → `meritdata-platform-integration`
+
+## 主题路由
+
+> **优先级规则**：⭐ = **权威来源**（公司研发文档，优先读） / 📘 = **兼容参考**（工业互联codex，仅作为对照）
+
+| 任务 | 权威来源 ⭐ | 兼容参考 📘 |
+| --- | --- | --- |
+| 启动流程实例 | ⭐ [`references/api/攻略-01-流程API-章节03_启动流程实例接口.md`](references/api/攻略-01-流程API-章节03_启动流程实例接口.md) | 📘 [`references/api-reference.md`](references/api-reference.md) |
+| 完成任务 | ⭐ [`references/api/攻略-01-流程API-章节05_完成任务接口.md`](references/api/攻略-01-流程API-章节05_完成任务接口.md) | — |
+| 查看追踪 | ⭐ [`references/api/攻略-01-流程API-章节08_查看追踪接口.md`](references/api/攻略-01-流程API-章节08_查看追踪接口.md) | 📘 [`references/process-track.md`](references/process-track.md) |
+| 退回拟稿人 | ⭐ [`references/api/攻略-01-流程API-章节09_退回拟稿人接口.md`](references/api/攻略-01-流程API-章节09_退回拟稿人接口.md) | — |
+| 个人待办 | ⭐ [`references/api/攻略-01-流程API-章节12_个人待办.md`](references/api/攻略-01-流程API-章节12_个人待办.md) | 📘 [`references/todo-portal.md`](references/todo-portal.md) |
+| 阅知 | ⭐ [`references/api/攻略-01-流程API-章节13_阅知.md`](references/api/攻略-01-流程API-章节13_阅知.md) | — |
+| 监听表达式 | ⭐ [`references/listener/攻略-03-监听表达式-00_总览.md`](references/listener/攻略-03-监听表达式-00_总览.md) | 📘 [`references/listener-expression.md`](references/listener-expression.md) |
+| BPM 前端组件 | ⭐ [`references/components-ref/攻略-08-流程前端组件-00_总览.md`](references/components-ref/攻略-08-流程前端组件-00_总览.md) | 📘 [`references/components.md`](references/components.md) |
+| 自定义处理人 | — | 📘 [`references/custom-assignee.md`](references/custom-assignee.md) |
+| 流程模块设计 | ⭐ [`references/module-design-ref/攻略-07-流程模块设计-00_总览.md`](references/module-design-ref/攻略-07-流程模块设计-00_总览.md) | 📘 [`references/module-design.md`](references/module-design.md) |
+| 端到端开发样例 | ⭐ [`references/workflow/攻略-02-工作流程-00_总览.md`](references/workflow/攻略-02-工作流程-00_总览.md) | 📘 [`references/workflow-dev.md`](references/workflow-dev.md) |
+| BpmEngine 方法总览 | ⭐ [`references/bpm-engine-detail/12_四业务组件-4.1工作流BpmEngine.md`](references/bpm-engine-detail/12_四业务组件-4.1工作流BpmEngine.md) | 📘 [`references/api-reference.md`](references/api-reference.md) |
+
+### 快速入口（按场景）
+
+| 用户场景 | 读哪个文件 |
+|---------|-----------|
+| 启动流程实例（最常用）| `references/api/攻略-01-流程API-章节03_启动流程实例接口.md` |
+| 完成任务 | `references/api/攻略-01-流程API-章节05_完成任务接口.md` |
+| 退回 | `references/api/攻略-01-流程API-章节09_退回拟稿人接口.md` |
+| 查看流程追踪 | `references/api/攻略-01-流程API-章节08_查看追踪接口.md` |
+| 个人待办 | `references/api/攻略-01-流程API-章节12_个人待办.md` |
+| 添加监听器 | `references/listener/攻略-03-监听表达式-章节02_自定义_jar_包的实现流程.md` |
+| 完整后端开发 | `references/workflow/攻略-02-工作流程-章节04_后端工程业务类创建.md` |
+| 完整前端开发 | `references/workflow/攻略-02-工作流程-章节06_流程应用前端开发.md` |
+
+## 工作方式（Step 1/2/3/4）
+
+### Step 1：版本与契约前检
+
+- 从目标项目的依赖和部署包确认 BPM 模块版本、JDK、网关前缀和实际服务名
+- 先从目标 JAR、源码或已部署接口确认 `BpmEngine` 方法签名、参数和返回类型
+
+### Step 2：按权威性读取 reference
+
+- 优先读 ⭐ 权威来源（攻略）
+- 📘 兼容参考仅作为对照或补充信息
+- 如果攻略与原 references 冲突，**以攻略为准**
+
+### Step 3：实现
+
+- 流程、待办和人员接口必须使用目标平台的用户会话或服务身份认证
+- 服务端校验授权范围，不得通过匿名路径或 URL 白名单绕过认证
+- 前端组件的 props、事件和请求路径以目标项目已安装版本为准
+
+### Step 4：输出
+
+- 先写明目标 BPM 版本、已核验的依赖或接口来源
+- 给出业务数据保存、流程调用、权限校验和失败补偿的完整调用顺序
+- 删除、退回、跨服务同步等不可逆操作必须含最小验证场景和幂等策略
+
+## 🚨 常见错误
+
+| 错误 | 后果 | 正确做法 |
+| --- | --- | --- |
+| 凭历史示例推断 BpmEngine 签名 | 接口变更后调用失败 | 从目标 JAR/WSDL 核验 |
+| 通过 URL 白名单绕过认证 | 安全漏洞 | 服务端校验会话 |
+| 流程状态变更无幂等设计 | 重复触发 | 设计幂等键 |
+| 不区分审批人/处理人 | 流程错误 | 使用自定义处理人契约 |
+| 读取多个相似 references | token 浪费 | 优先读 ⭐ 权威来源 |
+
+## 边界
+
+- **不在本 skill 范围的**：
+  - 通用审批业务（不依赖平台 BPM）
+  - 后端基础设施 → `meritdata-platform-core`
+  - 前端组件 → `meritdata-platform-frontend`
+  - 平台集成接口 → `meritdata-platform-integration`
+- **强制要求**：版本未知时只提供定位和验证步骤，不生成精确的 `BpmEngine` 调用

package/skills/meritdata-platform-bpm/agents/openai.yaml

@@ -0,0 +1,36 @@
+display_name: "MeritData 平台 BPM"
+short_description: "MeritData BPM 工作流（BpmEngine、待办、流程追踪、门户待办同步）"
+default_prompt: |
+  meritdata-platform-bpm 处理 MeritData 平台 BPM 工作流场景。
+
+  适用场景：
+  - 流程定义、发起、审批、退回、撤回、待办、阅知、流程追踪
+  - BPM 表单/列表组件（BpmFormTools、BpmGridButtonsNew）
+  - 监听表达式、自定义处理人、门户待办同步
+
+  使用方式：
+  ```
+  meritdata-platform-bpm <BPM 需求>
+  ```
+
+  工作方式：
+  1. 先确认目标项目 BPM 版本、JDK、网关前缀、实际服务名
+  2. 从目标 JAR 或 Swagger 核验 BpmEngine 接口签名
+  3. 按主题路由读取 references/ 中的专题 md
+  4. 输出业务数据保存、流程调用、权限校验和失败补偿的完整调用顺序
+  5. 对不可逆操作给出幂等策略
+
+  8 个 references：
+  - api-reference.md（6.13.2 历史接口）
+  - components.md（BpmFormTools 等组件）
+  - listener-expression.md（监听器）
+  - custom-assignee.md（自定义处理人）
+  - todo-portal.md（门户待办同步）
+  - process-track.md（流程追踪）
+  - workflow-dev.md（端到端样例）
+  - module-design.md（流程模块设计）
+
+  强制约束：
+  - 版本未知时只提供定位和验证步骤
+  - 不生成精确的 BpmEngine 调用（需先核验）
+  - 不通过 URL 白名单绕过认证

package/skills/meritdata-platform-bpm/examples/leave-flow/README.md

@@ -0,0 +1,151 @@
+# BPM 示例：请假审批流程
+
+## 场景
+
+基于平台 BpmEngine 实现一个请假审批流程：员工提交申请 → 直属领导审批 → HR 备案。
+
+## 用户输入
+
+```text
+$meritdata-platform-bpm 做一个请假审批流程，支持发起、审批通过、退回和流程追踪
+```
+
+## 输出要素
+
+### 1. 流程定义 JSON
+
+```json
+{
+  "processKey": "leave_apply",
+  "processName": "请假申请",
+  "version": "1.0",
+  "nodes": [
+    {
+        "nodeKey": "start",
+        "nodeType": "START",
+        "nodeName": "提交申请"
+      },
+      {
+        "nodeKey": "manager_approve",
+        "nodeType": "APPROVAL",
+        "nodeName": "直属领导审批",
+        "assignee": "${assignee.manager}"
+      },
+      {
+        "nodeKey": "hr_record",
+        "nodeType": "APPROVAL",
+        "nodeName": "HR 备案",
+        "assignee": "role:hr"
+      },
+      {
+        "nodeKey": "end",
+        "nodeType": "END",
+        "nodeName": "结束"
+      }
+    ],
+    "edges": [
+      { "from": "start", "to": "manager_approve" },
+      { "from": "manager_approve", "to": "hr_record", "condition": "approved" },
+      { "from": "manager_approve", "to": "start", "condition": "rejected" }
+    ]
+}
+```
+
+### 2. 业务表
+
+```sql
+CREATE TABLE T_LEAVE (
+    ID BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键',
+    PROCESS_INSTANCE_ID VARCHAR(64) COMMENT 'BPM 实例 ID',
+    USER_ID BIGINT NOT NULL COMMENT '申请人 ID',
+    LEAVE_TYPE VARCHAR(32) NOT NULL COMMENT '请假类型',
+    START_DATE DATE NOT NULL COMMENT '开始日期',
+    END_DATE DATE NOT NULL COMMENT '结束日期',
+    DAYS INT NOT NULL COMMENT '请假天数',
+    REASON VARCHAR(500) COMMENT '请假原因',
+    STATUS VARCHAR(32) NOT NULL DEFAULT 'PENDING' COMMENT '状态',
+    CREATE_BY VARCHAR(64) COMMENT '创建人',
+    CREATE_TIME DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    UPDATE_BY VARCHAR(64) COMMENT '更新人',
+    UPDATE_TIME DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    VERSION INT NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
+    IS_DELETED TINYINT NOT NULL DEFAULT 0 COMMENT '逻辑删除',
+    PRIMARY KEY (ID),
+    KEY IDX_LEAVE_USER (USER_ID),
+    KEY IDX_LEAVE_PROCESS (PROCESS_INSTANCE_ID)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='请假申请表';
+```
+
+### 3. Controller
+
+```java
+@RestController
+@RequestMapping("/api/leave")
+public class LeaveController {
+
+    @Autowired
+    private BpmEngine bpmEngine;
+
+    @PostMapping("/apply")
+    public ResultBody<LeaveApplyResult> apply(@Valid @RequestBody LeaveApplyParam param) {
+        // 1. 创建业务数据
+        // 2. 启动 BPM 流程
+        // 3. 关联 PROCESS_INSTANCE_ID
+        // 4. 返回
+    }
+
+    @PostMapping("/{processInstanceId}/approve")
+    public ResultBody<Void> approve(@PathVariable String processInstanceId,
+                                     @RequestBody ApprovalParam param) {
+        // 调用 BpmEngine 完成审批节点
+    }
+
+    @PostMapping("/{processInstanceId}/reject")
+    public ResultBody<Void> reject(@PathVariable String processInstanceId,
+                                    @RequestBody RejectParam param) {
+        // 调用 BpmEngine 退回
+    }
+
+    @GetMapping("/{processInstanceId}/track")
+    public ResultBody<ProcessTrackResult> track(@PathVariable String processInstanceId) {
+        // 调用 BpmEngine 获取流程追踪
+    }
+}
+```
+
+### 4. 前端组件
+
+使用 `BpmFormTools` 嵌入 BPM 表单组件：
+
+```vue
+<template>
+  <BpmFormTools :process-key="'leave_apply'" :business-key="leave.id" />
+</template>
+```
+
+使用 `BpmGridButtonsNew` 嵌入审批按钮：
+
+```vue
+<template>
+  <BpmGridButtonsNew
+    :process-instance-id="leave.processInstanceId"
+    :tasks="leave.tasks"
+    @approve="handleApprove"
+    @reject="handleReject" />
+</template>
+```
+
+## 关键决策
+
+1. **流程定义**：存于 `processes/leave_apply.json`
+3. **状态机**：PENDING / APPROVED / REJECTED / HR_RECORDED
+4. **幂等**：使用 `processInstanceId` 作为业务唯一键
+5. **补偿**：审批通过后调用 HR 备案接口（消息补偿）
+
+## 相关 References
+
+- [`api-reference.md`](../../references/api-reference.md)（6.13.2 接口）
+- [`components.md`](../../references/components.md)（BPM 组件）
+- [`listener-expression.md`](../../references/listener-expression.md)（监听器）
+- [`custom-assignee.md`](../../references/custom-assignee.md)（自定义处理人）
+- [`process-track.md`](../../references/process-track.md)（流程追踪）

package/skills/meritdata-platform-bpm/references/api//346/224/273/347/225/245-01-/346/265/201/347/250/213API-/347/253/240/350/212/20201_/345/211/215/347/275/256/346/235/241/344/273/266.md

@@ -0,0 +1,11 @@
+---
+name: 攻略-01-流程API-章节01_前置条件
+description: 前置条件 — 美林平台 BPM 流程 HTTP API 接口全集（启动流程、完成任务、追踪、阅知、退回等）
+keywords: [BPM, 流程API, 工作流, 启动流程, 完成任务, 追踪, 退回, 阅知, Camunda, 前置条件]
+use-cases: [BPM 流程 API 调用, 流程审批集成, 流程追踪, 流程退回]
+source-section: 无编号. 前置条件
+source-file: 应用开发平台-流程管理-使用攻略（一）：流程API接口.md
+---
+
+# 前置条件
+​        引入cloud-system-bpm-module-core包 版本为6.13.2