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

package/skills/meritdata-platform-bpm/references/components.md

@@ -0,0 +1,618 @@
+**版本**：V1.0
+**日期**：2026-05-19
+**说明**：BPM 工作流前端组件的历史用法索引；服务名、路由和组件行为必须按目标项目版本核验。
+---
+
+## 目录
+
+- [概述](#概述)
+- [一、组件与方法概览表](#一组件与方法概览表)
+- [二、BpmFormTools - BPM表单工具组件](#二bpmformtools---bpm表单工具组件)
+- [三、BpmGridButtonsNew - BPM表格按钮组件](#三bpmgridbuttonsnew---bpm表格按钮组件)
+- [四、后端BpmEngine核心接口](#四后端bpmengine核心接口)
+- [五、附录](#五附录)
+
+## 概述
+
+示例中的 `<business-service>` 仅表示业务服务客户端键。先确认目标项目已安装组件的 props、事件、网关前缀和认证拦截器，再复制任何调用代码；列表、表单和删除接口均须在服务端重新校验当前用户的数据范围。
+### 使用步骤：
+**1. 流程管理-流程Key，绑定二开服务某个模块的页面表单**
+在二开模块中，需要先与流程定义Key进行绑定。流程定义Key由流程管理员在流程设计器中创建，绑定后方可使用BPM组件进行流程操作。
+**2. 二开表格页需要新建、删除流程实例及业务数据、需要根据流程权限及流程状态对数据进行过滤，使用BpmGridButtonsNew组件**
+当二开模块需要在列表页展示业务流程数据时，使用 `BpmGridButtonsNew` 组件提供新建、我的申请、我的审批等按钮，通过组件事件处理查询、新建、删除等操作。
+1）引入组件，procDefKey为第一步创建的流程Key，传入组件
+```javascript
+  bbpm-grid-buttons-new
+            :procDefKey="procDefKey"
+            @bpm-query="queryBpm"
+            @bpm-delete="deleteRow"
+          />
+```
+2）需要改造二开接口，查询接口需要有procDefKey、bpmStatus的查询参数；删除的业务接口添加对流程实例的删除(参考5.4 删除流程实例)
+```javascript
+    // 查询数据
+    queryPageData() {
+      // 调用后端API查询列表
+      this.axios['cloud-system-bpm-demo']
+        .post('/page/procExample/page', {
+          procDefKey: this.procDefKey,
+          bpmStatus: this.bpmStatus,
+          pageNumber: this.currentPage,
+          pageSize: this.pageSize
+        })
+        .then(res => {
+          this.gridData = res.data.rows;
+          this.total = res.data.total;
+        });
+    },
+```
+```java
+   // 二开查询方法改造：
+	// 添加流程数据查询
+   		Map<String, Object> formQuery = new HashMap<>();
+        long firstResult = 0L;
+        long singleQueryData = 1000L;
+        List<MpUnitExterTransfer> applyData = new ArrayList<>();
+        List<String> businessIds = new ArrayList<>();
+        formQuery.put("BpmStatus", param.get("bpmStatus"));
+        ResultBody<GridView> procData = bpmEngine.queryMainForms(JSON.toJSONString(formQuery), param.get("procDefKey").toString(), firstResult, singleQueryData);
+        if (procData.isSuccess()) {
+            List<Map<String, Object>> listData = new ArrayList<>();
+            listData = procData.getData().getRows();
+            listData.stream().forEach(item -> {
+                // 获取二开业务数据，以下为示例：
+                MpUnitExterTransfer mpUnitExterTransfer =new MpUnitExterTransfer();
+                mpUnitExterTransfer.setBusinessId((item.get("businessId") == null ? "" : item.get("businessId")).toString());
+                mpUnitExterTransfer.setLastTime((item.get("updateTime") == null ? "" : item.get("updateTime")).toString());
+                mpUnitExterTransfer.
+                setFlowAuthorNames((item.get("flowAuthorNames") == null ? "" : item.get("flowAuthorNames")).toString());
+                mpUnitExterTransfer.setNodeNames((item.get("nodeNames") == null ? "" : item.get("nodeNames")).toString());
+                businessIds.add(item.get("businessId").toString());
+                applyData.add(mpUnitExterTransfer);
+            });
+        }
+
+	// 进行二开业务逻辑操作......
+ 	// 最终合并数据，返回GridView
+        data.forEach(item -> {
+            applyData.stream().filter(item1 -> item.getId().equals(item1.getBusinessId()))
+                    .forEach(item1 -> {
+                        item.setNodeNames(item1.getNodeNames());
+                        item.setFlowAuthorNames(item1.getFlowAuthorNames());
+                        item.setLastTime(item1.getLastTime());
+                    });
+        });
+        return new GridView(data, l);
+```
+**3.二开表单页需要进行流程流转，发送、填写意见、流程追踪等操作，需要使用bpmFormTools组件**
+当用户在表单页需要发起审批、填写意见、查看流程进度时，使用 `BpmFormTools` 组件集成流程操作按钮，在init/save回调中处理业务数据与流程的关联。
+1）引入组件，procDefKey为第一步创建的流程Key，传入组件
+```javascript
+   b!-- BPM工具栏（必须放在表单开头） -->
+    bbpm-form-tools
+      :procDefKey="procDefKey"
+      @init="init"
+      @save="save"
+      ref="bpmformtools"
+    />
+```
+2）引入初始化及保存方法，传入组件
+```javascript
+// 初始化表单（由bpm-form-tools调用）
+    init(params) {
+      if (params.id == '') {
+        // 新建流程 - 获取当前用户信息
+        this.axios['<system-service-client>']
+          .get('/api/ou/user/session')
+          .then(result => {
+            this.example.name = result.name;
+            this.example.belongDept = result.deptName;
+            this.example.project = result.name + '_' + this.formatDate(new Date()) + '_出差报销';
+            params.callback(this.example);
+          });
+      } else {
+        // 打开已有流程 - 加载业务数据（二开接口）
+        this.axios['cloud-system-bpm-demo']
+          .post('/get', { id: params.id })
+          .then(res => {
+            Object.assign(this.example, res.data);
+            this.example.undoId = params.undoId;
+            params.callback(this.example);
+          });
+      }
+    },
+
+    // 保存业务数据（由bpm-form-tools调用）
+    save(bpmSaveAfter) {
+        // 二开接口
+      this.axios['cloud-system-bpm-demo']
+        .post('/update', this.example)
+        .then(res => {
+          Object.assign(this.example, res.data);
+          // 流程相关逻辑处理
+          // 设置流程相关变量（必须）
+          this.example['bpmSubject'] = res.data.project;   // 流程标题（必填）
+          this.example['bpmUrgent'] = this.example.urgency;  // 紧急程度
+          this.example['bpmSecret'] = this.example.mj;   // 密级
+          // 开展二开相关业务逻辑....
+          // 必须调用此回调，触发流程保存后处理
+          bpmSaveAfter(this.example);
+        });
+    },
+```
+### 全局安装方式
+```javascript
+// cloud-module-bpm 全局安装
+import cloudModuleBpm from 'cloud-module-bpm';
+Vue.use(cloudModuleBpm);
+```
+---
+## 一、组件与方法概览表
+### 1.1 前端组件
+| 来源 | 组件/方法名 | 作用场景 | 说明 |
+|------|------------|----------|------|
+| bpm-form-tools.vue | BpmFormTools | BPM表单工具组件 | 流程表单核心组件，集成发送、暂存等流程操作按钮 |
+| bpm-grid-buttons-new.vue | BpmGridButtonsNew | BPM表格按钮组件 | 流程列表页操作按钮，提供新建、我的申请、我的审批等 |
+### 1.2 后端接口
+| 来源类 | 方法名 | 作用场景 | 说明 |
+|------|--------|----------|------|
+| BpmEngine | startProcess | 启动流程 | 根据流程定义Key和businessId启动流程 |
+| BpmEngine | ruleEngineInit | 规则引擎初始化 | 查询流程按钮配置信息，初始化流程操作界面 |
+| BpmEngine | ruleEngineRun | 规则引擎执行 | 根据businessId查询待办任务 |
+| BpmEngine | complete | 完成任务 | 完成当前任务，推进流程到下一节点 |
+| BpmEngine | deleteProcInsts | 删除流程实例 | 根据businessIds删除流程实例 |
+| BpmEngine | queryMainForms | 流程实例查询 | 分页查询流程实例列表 |
+| BpmEngine | getPage | 文字追踪 | 获取流程流转路径文字信息 |
+| BpmEngine | getGraphTrack | 图表追踪 | 获取流程图形追踪信息 |
+| BpmEngine | getOpinions | 审批意见 | 获取流程审批意见列表 |
+| BpmEngine | addOrUpdate | 填写意见 | 在节点填写审批意见 |
+| BpmEngine | getUndoPage | 个人待办列表 | 获取当前用户的待办任务列表 |
+### 1.3 MeritBPM方法与后端API对应关系
+| MeritBPM方法 | 后端API | 说明 |
+|--------------|---------|------|
+| MeritBPM.create / initRuleEngine | POST /api/engine/bpm/ruleengine/init/{procDefKey} | 创建流程/初始化规则引擎 |
+| MeritBPM.open / runRuleEngine | POST /api/engine/bpm/ruleengine/run | 打开流程/运行规则引擎 |
+| MeritBPM.startProcess | POST /api/engine/bpm/{procDefKey}/startprocess | 发起流程 |
+| MeritBPM.validatePermit | POST /api/engine/bpm/{procDefKey}/validate/permit | 验证流程权限 |
+| MeritBPM.openProcTrackWindow | POST /api/engine/track/port | 打开流程跟踪窗口 |
+---
+## 二、BpmFormTools - BPM表单工具组件
+**文件路径**: `cloud-module-bpm/packages/bpm-form-tools/bpm-form-tools.vue`
+**功能说明**: BPM表单核心工具组件，集成流程操作按钮（发送、暂存等），是流程表单页的必选组件。
+### 2.1 Props属性
+| 属性名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| procDefKey | String | true | 流程定义Key |
+### 2.2 Events事件
+| 事件名 | 说明 | 返回值 |
+|--------|------|--------|
+| init | 初始化事件，返回业务数据对象 | `{id, undoId, params, callback}` |
+| save | 保存事件，保存业务数据 | `{bpmSaveAfter, bpmBtn}` |
+### 2.3 组件内部状态
+| 状态名 | 类型 | 说明 |
+|--------|------|------|
+| ruleEngine | Object | 规则引擎对象，包含businessId、procInstId、undoId等 |
+| MeritBPM | Object | BPM工具对象 |
+### 3.4 实际使用示例（form-edit.vue）
+```vue
+<template>
+  bel-form ref="example" :model="example" label-width="80px" style="padding: 16px;width:850px;margin:20px auto;">
+    b!-- BPM工具栏（必须放在表单开头） -->
+    bbpm-form-tools
+      :procDefKey="procDefKey"
+      @init="init"
+      @save="save"
+      ref="bpmformtools"
+    />
+
+    bel-row><el-col style="font-size:24px;font-weight:bold">出差费用报销单</el-col>b/el-row>
+
+    b!-- 业务表单字段 ... -->
+  b/el-form>
+b/template>
+
+<script>
+import { MeritBPM } from 'cloud-module-bpm/packages/utils/merit-bpm.js';
+
+export default {
+  data() {
+    return {
+      MeritBPM,
+      procDefKey: 'Process_Demo1',
+      example: {
+        id: '',
+        project: '',
+        name: '',
+        belongDept: '',
+        amount: 0,
+        urgency: 'common',
+        mj: '1'
+      }
+    };
+  },
+  methods: {
+    // 初始化表单（由bpm-form-tools调用）
+    init(params) {
+      if (params.id == '') {
+        // 新建流程 - 获取当前用户信息
+        this.axios['<system-service-client>']
+          .get('/api/ou/user/session')
+          .then(result => {
+            this.example.name = result.name;
+            this.example.belongDept = result.deptName;
+            this.example.project = result.name + '_' + this.formatDate(new Date()) + '_出差报销';
+            params.callback(this.example);
+          });
+      } else {
+        // 打开已有流程 - 加载业务数据
+        this.axios['cloud-system-bpm-demo']
+          .post('/get', { id: params.id })
+          .then(res => {
+            Object.assign(this.example, res.data);
+            this.example.undoId = params.undoId;
+            params.callback(this.example);
+          });
+      }
+    },
+
+    // 保存业务数据（由bpm-form-tools调用）
+    save(bpmSaveAfter) {
+      this.axios['cloud-system-bpm-demo']
+        .post('/update', this.example)
+        .then(res => {
+          Object.assign(this.example, res.data);
+          // 设置流程相关变量（必须）
+          this.example['bpmSubject'] = res.data.project;   // 流程标题（必填）
+          this.example['bpmUrgent'] = this.example.urgency;  // 紧急程度
+          this.example['bpmSecret'] = this.example.mj;   // 密级
+          // 必须调用此回调，触发流程保存后处理
+          bpmSaveAfter(this.example);
+        });
+    },
+
+    formatDate(date) {
+      return date.toISOString().split('T')[0];
+    }
+  }
+};
+</script>
+```
+---
+## 三、BpmGridButtonsNew - BPM表格按钮组件
+**文件路径**: `cloud-module-bpm/packages/bpm-grid-buttons-new/bpm-grid-buttons-new.vue`
+**功能说明**: BPM流程列表页操作按钮组件，提供新建、我的申请、我的审批、所有流程等下拉菜单按钮。
+### 3.1 Props属性
+| 属性名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| procDefKey | String | true | 流程定义Key |
+| isShowButton | Boolean | false | 是否显示按钮（默认true） |
+| isDisabledAddButton | Boolean | false | 新建按钮是否禁用 |
+### 3.2 Events事件
+| 事件名 | 说明 | 返回值 |
+|--------|------|--------|
+| bpm-query | 查询流程 | `bpmStatus` 流程状态值 |
+| bpm-delete | 删除流程 | - |
+### 3.3 流程状态值说明
+| 状态值 | 说明 | 所属菜单 |
+|--------|------|---------|
+| my | 我的申请 | 我的申请 |
+| mydraft | 我的草稿 | 我的申请 |
+| mytralk | 我的跟踪 | 我的申请 |
+| myover | 我的已完结 | 我的申请 |
+| approve | 待我审批 | 我的审批 |
+| all | 所有流程 | 所有流程 |
+### 4.4 实际使用示例（Grid.vue）
+```vue
+<template>
+  bel-lontainer>
+    bel-main style="padding: 8px 12px;">
+      b!-- BPM流程按钮组 -->
+      bel-row justify="spale-between" type="flex">
+        <el-col :span="7">
+          bbpm-grid-buttons-new
+            :procDefKey="procDefKey"
+            @bpm-query="queryBpm"
+            @bpm-delete="deleteRow"
+          />
+        </el-col>
+        <el-col :span="7">
+          bel-input
+            v-model="keyword"
+            @change="queryKeyword"
+            placeholder="请输入标题"
+            clearable
+            suffix-icon="el-icon-search"
+          >
+          b/el-input>
+        </el-col>
+      b/el-row>
+
+      b!-- 业务列表 -->
+      bel-table
+        stripe
+        ref="tables"
+        :data="gridData"
+        style="width: 100%"
+        :height="tableHeight"
+        @selection-change="handleSelectionChange"
+      >
+        bel-table-column type="selection" width="55" :selectable="checkDel">b/el-table-column>
+        bel-table-column prop="project" label="标题">b/el-table-column>
+        bel-table-column prop="procDealStatus" label="处理状态">
+          <template slot-scope="scope">
+            bel-tag>{{ statusLabel(slope.row.procDealStatus) }}b/el-tag>
+          b/template>
+        b/el-table-column>
+        bel-table-column label="操作" width="100">
+          <template slot-scope="scope">
+            bel-button icon="el-icon-edit" @click="editRow(slope.$index, slope.row)" size="small">b/el-button>
+          b/template>
+        b/el-table-column>
+      b/el-table>
+
+      bel-pagination
+        @size-change="handleSizeChange"
+        @lurrent-change="handleCurrentChange"
+        :lurrent-page="currentPage"
+        :page-size="pageSize"
+        layout="total, sizes, prev, pager, next, jumper"
+        :total="total"
+      >b/el-pagination>
+    b/el-main>
+  b/el-lontainer>
+b/template>
+
+<script>
+import { MeritBPM } from 'cloud-module-bpm/packages/utils/merit-bpm.js';
+
+export default {
+  data() {
+    return {
+      MeritBPM,
+      tableHeight: window.innerHeight - 180,
+      procDefKey: 'Process_Demo1',
+      selectionRows: [],
+      bpmStatus: 'my'
+    };
+  },
+  created() {
+    // 初始化时验证流程权限
+    this.MeritBPM.validatePermit(this, this.procDefKey, null);
+    // 将刷新方法挂载到window，用于表单关闭后刷新
+    window.refreshBpmGrid = () => {
+      this.queryBpm(this.bpmStatus);
+    };
+    this.initLoadPage();
+  },
+  methods: {
+    // 由按钮组件触发的查询
+    queryBpm(type) {
+      this.$refs.tables.bodyWrapper.scrollTop = 0;
+      this.currentPage = 1;
+      this.bpmStatus = type;
+      this.queryPageData();
+    },
+
+    // 打开流程（办理）
+    editRow(index, row) {
+      MeritBPM.open(this, { businessId: row.id }, {});
+    },
+
+    // 删除流程
+    deleteRow() {
+      if (this.selectionRows.length === 0) {
+        this.$message.warning('请选择需要删除的流程');
+        return;
+      }
+      let delIds = this.selectionRows.map(row => row.id);
+      // 删除业务数据（后端删除流程实例）
+      this.batchDeleteExample({ ids: delIds });
+    },
+
+    // 选择框变化
+    handleSelectionChange(rows) {
+      this.selectionRows = rows;
+    },
+
+    // 判断行是否可选（草稿或管理员可删除）
+    checkDel(row) {
+      return row.procDealStatus === 'draft' || MeritBPM.procManagePermit;
+    },
+
+    // 分页大小变化
+    handleSizeChange(val) {
+      this.pageSize = val;
+      this.currentPage = 1;
+      this.queryPageData();
+    },
+
+    // 页码变化
+    handleCurrentChange(val) {
+      this.$refs.tables.bodyWrapper.scrollTop = 0;
+      this.currentPage = val;
+      this.queryPageData();
+    },
+
+    // 状态标签
+    statusLabel(status) {
+      return 'status.' + status;
+    },
+
+    // 初始化加载
+    initLoadPage() {
+      this.currentPage = 1;
+      this.queryPageData();
+    },
+
+    // 查询数据
+    queryPageData() {
+      // 调用后端API查询列表
+      this.axios['cloud-system-bpm-demo']
+        .post('/page/procExample/page', {
+          procDefKey: this.procDefKey,
+          bpmStatus: this.bpmStatus,
+          pageNumber: this.currentPage,
+          pageSize: this.pageSize
+        })
+        .then(res => {
+          this.gridData = res.data.rows;
+          this.total = res.data.total;
+        });
+    },
+
+    // 批量删除
+    batchDeleteExample({ ids, callback }) {
+      this.axios['cloud-system-bpm-demo']
+        .post('/delete/batch', { ids: ids.join(',') })
+        .then(res => {
+          if (callback) callback(res.data);
+          this.initLoadPage();
+        });
+    }
+  }
+};
+</script>
+```
+---
+## 四、后端BpmEngine核心接口
+完整包路径：`com.meritdata.cloud.bpm.core.BpmEngine`
+### 4.1 方法概览表
+| 来源类 | 方法名 | 作用场景 | 说明 |
+|------|--------|----------|------|
+| BpmEngine | startProcess | 启动流程 | 根据流程定义Key和businessId启动流程 |
+| BpmEngine | ruleEngineInit | 规则引擎初始化 | 查询流程按钮配置信息，初始化流程操作界面 |
+| BpmEngine | ruleEngineRun | 规则引擎执行 | 根据businessId查询待办任务 |
+| BpmEngine | complete | 完成任务 | 完成当前任务，推进流程到下一节点 |
+| BpmEngine | deleteProcInsts | 删除流程实例 | 根据businessIds删除流程实例 |
+| BpmEngine | queryMainForms | 流程实例查询 | 分页查询流程实例列表 |
+| BpmEngine | getPage | 文字追踪 | 获取流程流转路径文字信息 |
+| BpmEngine | getGraphTrack | 图表追踪 | 获取流程图形追踪信息 |
+### 4.2 启动流程
+```java
+@Autowired
+private BpmEngine bpmEngine;
+
+@Autowired
+private SessionUtils sessionUtils;
+
+/**
+ * 启动流程
+ */
+public MainFormDTO startProcess(String procDefKey, Map<String, Object> variables) {
+    // 设置拟稿人
+    variables.put("bpmDrafterId", sessionUtils.getCurrentUserName());
+
+    // 启动流程
+    ResultBody<MainFormDTO> resultBody = bpmEngine.startProcess(procDefKey, variables);
+
+    if (resultBody != null && resultBody.isSuccess()) {
+        return resultBody.getData();
+    }
+    return null;
+}
+```
+### 4.3 查询流程实例列表（分页）
+```java
+@Autowired
+private BpmEngine bpmEngine;
+
+/**
+ * 分页查询流程实例
+ */
+public GridView<Map> pageProcExample(String procDefKey, String bpmStatus, int pageNumber, int pageSize) {
+    // 构建流程查询条件
+    MainFormQueryDTO formQuery = new MainFormQueryDTO();
+    formQuery.setBpmStatus(bpmStatus);
+
+    // 调用BpmEngine查询流程主表
+    ResultBody<GridView> resultBody = bpmEngine.queryMainForms(
+        JSONUtil.toJsonStr(formQuery), procDefKey, (pageNumber - 1) * pageSize, pageSize
+    );
+
+    List<Map> mainForms = new ArrayList<>();
+    long total = 0;
+    if (resultBody != null && resultBody.isSuccess() && resultBody.getData() != null) {
+        mainForms = resultBody.getData().getRows();
+        total = resultBody.getData().getTotal();
+    }
+
+    // 将流程数据与业务数据关联
+    // ... 关联业务表数据 ...
+
+    return new GridView<>(mainForms, total);
+}
+```
+### 5.4 删除流程实例
+```java
+@Autowired
+private BpmEngine bpmEngine;
+
+/**
+ * 批量删除流程实例
+ * 注意：先删流程，再删业务数据
+ */
+public boolean deleteBatch(List<String> businessIds) {
+    // 1. 调用BpmEngine删除流程实例
+    ResultBody<Boolean> resultBody = bpmEngine.deleteProcInsts(businessIds);
+
+    if (resultBody != null && resultBody.isSuccess() && resultBody.getData()) {
+        // 2. 流程删除成功后，删除业务表数据
+        exampleRepository.deleteAllByIds(businessIds);
+        return true;
+    }
+    return false;
+}
+```
+### 5.5 获取流程跟踪信息
+```java
+/**
+ * 获取流程文字跟踪信息
+ */
+public List<ProcTrackDTO> getFlowSteps(String procInstId) {
+    ResultBody<List<ProcTrackDTO>> resultBody = bpmEngine.getPage(procInstId, null, null);
+    if (resultBody != null && resultBody.isSuccess()) {
+        return resultBody.getData();
+    }
+    return Collections.emptyList();
+}
+
+/**
+ * 获取流程图形跟踪信息
+ */
+public Map getFlowGraph(String procInstId) {
+    ResultBody<Map> resultBody = bpmEngine.getGraphTrack(procInstId, null, null);
+    if (resultBody != null && resultBody.isSuccess()) {
+        return resultBody.getData();
+    }
+    return Collections.emptyMap();
+}
+```
+---
+## 五、附录
+### 5.1 BPM组件与API对应关系
+| 前端组件 | MeritBPM方法 | 后端API | 说明 |
+|----------|-------------|---------|------|
+| BpmFormTools | lreate/initRuleEngine | POST /api/engine/bpm/ruleengine/init/{procDefKey} | 创建流程/初始化规则引擎 |
+| BpmFormTools | runRuleEngine | POST /api/engine/bpm/ruleengine/run | 运行规则引擎 |
+| BpmFormTools | startProcess | POST /api/engine/bpm/{procDefKey}/startprocess | 发起流程 |
+| BpmGridButtonsNew | validatePermit | POST /api/engine/bpm/{procDefKey}/validate/permit | 验证权限 |
+| - | openProcTrackWindow | POST /api/engine/track/port | 打开流程跟踪 |
+### 5.2 流程变量说明
+| 变量名 | 类型 | 说明 |
+|--------|------|------|
+| bpmSubject | String | 流程标题（必填） |
+| bpmUrgent | String | 紧急程度 |
+| bpmSecret | String | 密级 |
+| bpmDrafterId | String | 拟稿人ID |
+| businessId | String | 业务数据ID |
+| procInstId | String | 流程实例ID |
+| undoId | String | 待办ID |
+| procDefKey | String | 流程定义Key |
+### 5.3 流程状态值说明
+| 状态值 | 说明 | 使用场景 |
+|--------|------|---------|
+| draft | 草稿 | 流程未提交 |
+| running | 进行中 | 流程正在审批 |
+| approved | 已通过 | 流程审批通过 |
+| rejected | 已驳回 | 流程被驳回 |
+| cancelled | 已取消 | 流程已取消 |

package/skills/meritdata-platform-bpm/references/custom-assignee.md

@@ -0,0 +1,28 @@
+自定义人员用于在用户任务进入下一环节时，按业务条件返回候选处理人编码。历史 6.2/6.3 配置方式可能不同，先从目标 BPM 版本和已部署流程设计器确认字段与路由。
+## 1. 配置位置
+在流程设计器的用户任务人员配置中选择“自定义”。填写控制器标识、方法标识和可选的自定义条件；实际菜单名称以目标版本为准。
+## 2. 服务与路由契约
+服务名由 BPM 配置指向目标业务服务，例如：
+```properties
+meritdata.cloud.custom-service-name=<service-name>
+```
+历史路由形态为：
+```text
+/<service-name>/api/bpm/<controller>/getUserCode/<method>
+```
+其中 `<controller>` 和 `<method>` 由流程配置提供。先在目标服务的网关路由和 Controller 映射中验证该形态；不要复制历史示例服务名或路径。
+## 3. 请求与返回
+| 项目 | 要求 |
+| --- | --- |
+| 请求 | `POST`；参数为 `Map<String, String>`，可通过固定键 `customCondition` 传递业务条件 |
+| 返回 | `List<String>`，每项为目标环境中有效的人员编码 |
+| 校验 | 校验请求身份、业务对象权限、条件格式和返回人员的有效性及可见范围 |
+| 空结果 | 由流程定义或业务层明确处理，不能静默分配给默认用户 |
+## 4. 安全要求
+- BPM 到业务服务必须使用已认证的服务到服务调用，例如平台服务身份、OAuth2 客户端凭据或 mTLS，并按当前平台机制传递调用身份。
+- 业务服务必须授权该身份调用人员解析接口，并记录必要审计信息。
+- 不要在 Nacos 或网关中为 `getUserCode` 添加匿名、`permitAll` 或 URL 白名单绕过；这会让任意调用方枚举或影响流程处理人。
+## 5. 验证
+1. 用具有最小权限的已认证身份调用接口，确认无权业务对象被拒绝。
+2. 以有效和无效 `customCondition` 分别验证返回结果、空结果和错误处理。
+3. 在测试流程中确认返回编码与当前租户、组织和流程节点的处理人规则一致。