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

package/skills/meritdata-platform-bpm/references/bpm-engine-complete-methods.md

@@ -0,0 +1,150 @@
+# BpmEngine 完整方法清单（基于源码实测）
+
+> **来源**：`com.meritdata.cloud.bpm.core.BpmEngine.java`（位于 `cloud-system-bpm-module-core` 模块）
+> **类注解**：@RestController + @RequestMapping("/api/bpm/core")
+> **核实日期**：2026-09-10
+> **重要**：本文档基于源码实测，包含全部 **35 个方法**（skill 中此前只声明 13 个）
+> **关系**：本文档是 `api-reference.md` 的**完整补充**——后者是详细接口契约（2272 行），本文档是**方法索引**
+
+---
+
+## 一、13 个原方法（skill 历史声明）
+
+> ✅ **全部 13 个方法名与源码一致**（2026-09-10 核实通过）
+
+| # | 方法名 | URL | 返回类型 | 入参 | 备注 |
+|---|--------|-----|---------|------|------|
+| 1 | `ruleEngineInit` | `/ruleengine/init/{procDefKey}` | `ResultBody<RuleEngine>` | procDefKey: String, variables: Map | 规则引擎初始化 |
+| 2 | `ruleEngineRun` | `/ruleengine/run` | `ResultBody<RuleEngine>` | variables: Map | 规则引擎运行 |
+| 3 | `queryMainForms` | `/query/mainforms` | `ResultBody<GridView>` | mainFormQueryDtoJson: String, procDefKey: String, page: Long (0), rows: Long (20) | 流程实例分页查询 |
+| 4 | `startProcess` | `/{procDefKey}/startprocess` | `ResultBody<MainFormDTO>` | procDefKey: String, variables: Map | **唯一 throws Exception** |
+| 5 | `complete` | `/task/{id}/complete` | `ResultBody<MainFormDTO>` | id: String, variables: Map | 完成任务 |
+| 6 | `deleteProcInsts` | `/api/engine/bpm/delete/procinsts` | `ResultBody<Boolean>` | businessIds: List<String> (@RequestBody) | 删除流程实例 |
+| 7 | `processRetfirnode` | `/retfirnode/{businessId}` | `ResultBody<String>` | businessId: String, variables: Map | **注意拼写**（源码原样）|
+| 8 | `processRetprenode` | `/retprenode/{businessId}` | `ResultBody<String>` | businessId: String, variables: Map | **注意拼写**（源码原样）|
+| 9 | `getPage`（文字追踪重载）| `/step` | `ResultBody<List<ProcTrackDTO>>` | procInstId: String, mainFormId: String?, procDefId: String? | 流程文字追踪 |
+| 10 | `getGraphTrack` | `/graph` | `ResultBody<Map>` | procInstId: String, mainFormId: String?, procDefId: String? | 流程图形追踪 |
+| 11 | `getOpinions` | `/getOpinions` | `ResultBody<List<ProcOpinionDTO>>` | variables: Map | 获取审批意见 |
+| 12 | `addOrUpdate` | `/addOrUpdate` | `ResultBody<Boolean>` | variables: Map | 填写意见 |
+| 13 | `getUndoPage` | `/undoPage` | `ResultBody<GridView<UndoDTO>>` | variables: Map | 个人待办列表 |
+
+**重要提示**：`processRetfirnode` / `processRetprenode` 的非常规拼写在源码和 URL 注解中**完全一致**——并非 skill 笔误，是源码本身如此，**不应"修正"**。
+
+---
+
+## 二、补充的 22 个方法（skill 此前缺失）
+
+> **基于 2026-09-10 源码实测补充**——这些方法在 skill 中完全缺失
+
+### 2.1 流程实例查询（6 个）
+
+| # | 方法名 | URL | 返回类型 | 入参 |
+|---|--------|-----|---------|------|
+| 14 | `create` | `/deployment/create` (multipart) | `DeploymentWithDefinitionsVo` | upload: MultipartFile |
+| 15 | `queryMainFormsByBusinessId` | `/query/mainform` | `ResultBody<MainFormDTO>` | businessId: String |
+| 16 | `queryMainFormsByBusinessIds` | `/query/mainforms-businessIds` | `ResultBody<List<MainFormDTO>>` | businessIds: String |
+| 17 | `queryMainFormByProcDefKeys` | `/query/mainforms-procDefKeys` | `ResultBody<List<MainFormDTO>>` | procDefKeys: String |
+| 18 | `queryMyApply` | `/query/my-apply` | `ResultBody<GridView>` | mainFormQueryDtoJson, procDefKey, page, rows |
+| 19 | `queryMyApprove` | `/query/my-approve` | `ResultBody<GridView>` | mainFormQueryDtoJson, procDefKey, page, rows |
+
+### 2.2 流程操作辅助（8 个）
+
+| # | 方法名 | URL | 返回类型 | 入参 |
+|---|--------|-----|---------|------|
+| 20 | `validatePermit` | `/{procDefKey}/validate/permit` | `ResultBody<ProcPermitDTO>` | procDefKey: String |
+| 21 | `processRetRandomNodeStatus` | `/RetRandomNodeStatus/{businessId}/{toTaskDefKey}/{receiver}` | `ResultBody<String>` | businessId, toTaskDefKey, receiver, variables |
+| 22 | `getNodeTip` | `/tip` | `ResultBody<List>` | taskDefKey, procInstId?, mainFormId? |
+| 23 | `getPort` | `/port` | `ResultBody<String>` | 无 |
+| 24 | `getContent` | `/getContent` | `ResultBody<String>` | variables: Map |
+| 25 | `getPage`（**重载 #2 - 流程列表**）| `/page` | `ResultBody<GridView<ProcItemDTO>>` | variables: Map |
+| 26 | `getSendReadUsers` | `/process/getSendReadUsers/{taskId}` | `ResultBody<List<BpmUser>>` | taskId: String, variables: Map |
+| 27 | `sendingRead` | `/process/sendingRead/{procInstId}` | `ResultBody<String>` | procInstId, userCodes: Map<String,Object> |
+| 28 | `sendReadEnd` | `/process/sendReadEnd/{procInstId}` | `ResultBody<String>` | procInstId: String |
+| 29 | `getProcTypes` | `/query/proctypes` (GET) | `ResultBody<Map<String,String>>` | 无 |
+| 30 | `addFormAddress` | `/add/formaddress` | `ResultBody<Boolean>` | name, address, sort: Integer, typecode |
+| 31 | `getLatestProcDefId` | `/ruleengine/{procDefKey}` | `ResultBody<String>` | procDefKey: String |
+
+### 2.3 1.4.2 新增的 4 个查询接口（重大版本升级遗漏）
+
+| # | 方法名 | URL | 返回类型 | 入参 |
+|---|--------|-----|---------|------|
+| 32 | `queryMyUndo` | `/undo/query` | `ResultBody<GridView<UndoQueryResultVo>>` | queryDto: QueryUndoDto (@RequestBody) |
+| 33 | `queryMyInitiate` | `/mainform/query` | `ResultBody<GridView<MainformQueryResultVo>>` | queryDto: QueryMainformDto (@RequestBody) |
+| 34 | `queryProcMonitor` | `/procMonitor/query` | `ResultBody<GridView<MainMonitorQueryResultVo>>` | queryDto: QueryProcMonitorDto (@RequestBody) |
+| 35 | `queryProcByte` | `/procByte/query` | `ResultBody<GridView<ProcByteQueryResultVo>>` | queryDto: QueryProcByteDto (@RequestBody) |
+
+---
+
+## 三、`getPage` 重载方法说明（重要）
+
+`BpmEngine` 中存在**两个同名方法** `getPage`，绑定到不同 URL：
+
+| 重载 | URL | 返回类型 | 入参 | 用途 |
+|------|-----|---------|------|------|
+| #1 文字追踪 | `/step` | `ResultBody<List<ProcTrackDTO>>` | (procInstId, mainFormId?, procDefId?) | 流程文字追踪 |
+| #2 流程列表 | `/page` | `ResultBody<GridView<ProcItemDTO>>` | variables: Map | 流程列表查询 |
+
+skill 中描述的 `getPage` 未区分这两个重载，**调用时需注意 URL 区分**。
+
+---
+
+## 四、BPM Feign 接口（基于源码实测）
+
+### 4.1 IBpmCustomUserServiceClient
+
+- **类路径**：`com.meritdata.cloud.bpm.engine.feign`（模块 `cloud-system-bpm-engine`，**非** module-core）
+- **@FeignClient**：`${meritdata.cloud.custom-service-name}`, contextId=`processUserCustomServiceClient`, configuration=CloudFeignConfiguration
+- **方法（1 个）**：
+
+| 方法名 | 返回类型 | 入参 | URL |
+|--------|---------|------|-----|
+| `getUserCodes` | `List<String>` | controllerParameter: String (@PathVariable), methodsParameter: String (@PathVariable), params: Map (@RequestParam) | `POST /api/bpm/{controllerParameter}/getUserCode/{methodsParameter}` |
+
+### 4.2 ITaskRestServiceClient
+
+- **类路径**：`com.meritdata.cloud.bpm.core.feign`（模块 `cloud-system-bpm-module-core`，**非** engine.feign）
+- **@FeignClient**：`cloud-system-bpm-engine`, contextId=`taskRestServiceClient`
+- **方法（1 个有效方法）**：
+
+| 方法名 | 返回类型 | 入参 | URL |
+|--------|---------|------|-----|
+| `queryTasks` | `List<TaskVo>` | entity: String (@RequestBody), firstResult: Integer (@RequestParam), maxResults: Integer (@RequestParam) | `POST /engine-rest/task` |
+
+### 4.3 IDeploymentRestServiceClient
+
+- **类路径**：`com.meritdata.cloud.bpm.core.feign`（**非** engine.feign）
+- **@FeignClient**：`cloud-system-bpm-engine`, contextId=`deploymentRestServiceClient`
+- **方法（1 个）**：
+
+| 方法名 | 返回类型 | 入参 | URL |
+|--------|---------|------|-----|
+| `create` | `DeploymentWithDefinitionsVo` | upload: MultipartFile (@RequestPart) | `POST /engine-rest/deployment/create` |
+
+### 4.4 修正要点
+
+| 错误描述 | 正确描述 |
+|---------|---------|
+| `IBpmCustomUserServiceClient` 在 module-core | 实际在 `cloud-system-bpm-engine` 模块，包 `com.meritdata.cloud.bpm.engine.feign` |
+| `ITaskRestServiceClient` 在 `engine.feign` 包 | 实际在 `com.meritdata.cloud.bpm.core.feign` |
+| `IDeploymentRestServiceClient` 在 `engine.feign` 包 | 实际在 `com.meritdata.cloud.bpm.core.feign` |
+
+---
+
+## 五、与 skill api-reference.md 的关系
+
+| 文档 | 关系 |
+|------|------|
+| `api-reference.md`（2272 行）| **详细接口契约**——含完整 URL/参数/响应示例/网关前缀/调用样例。**未修改**，作为权威来源 |
+| **本文档**（35 方法索引）| **方法索引 + 重载/异常标注**——基于源码实测的"快速查询表" |
+
+两者互补：
+- 写代码 → 看 `api-reference.md`（含示例）
+- 选方法 → 看本文档（快速索引）
+
+---
+
+## 🔗 相关文档
+
+- `dev-docs/12_四业务组件-4.1工作流BpmEngine.md`（拆分源文件，Camunda 7.12.0 已核实）
+- `references/api-reference.md`（详细接口契约）
+- `references/components-ref/`（BPM 前端组件）

package/skills/{meritdata-dev-docs-file-finder/references/dev-docs → meritdata-platform-bpm/references/bpm-engine-detail}/12_/345/233/233/344/270/232/345/212/241/347/273/204/344/273/266-4.1/345/267/245/344/275/234/346/265/201BpmEngine.md

@@ -13,13 +13,13 @@ related: [16, 11]
 > **行号范围**：L2179–L2235
 
 ## 🎯 一句话
-基于 Camunda BPM 7.21.0 的工作流引擎，对外提供 13 个方法覆盖流程启动、审批、退回、删除、待办、追踪、意见等全场景。
+基于 Camunda BPM 7.12.0 的工作流引擎，对外提供 13 个方法覆盖流程启动、审批、退回、删除、待办、追踪、意见等全场景。
 
 ## 📋 接口/方法清单
 
 ### 4.1 工作流组件-详细参考：应用开发平台-流程管理-使用攻略（一)：流程API接口.md
 
-基于 Camunda BPM 7.21.0 的工作流引擎，所有对外接口均通过 `BpmEngine` 提供。
+基于 Camunda BPM 7.12.0 的工作流引擎，所有对外接口均通过 `BpmEngine` 提供。
 
 **二开服务使用方式**：通过 `@Autowired` 注入 `BpmEngine`，直接调用其方法。