-
-
Notifications
You must be signed in to change notification settings - Fork 9k
Add comprehensive documentation for existing WeChat Enterprise workflow approval support #3687
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
Draft
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
141 changes: 141 additions & 0 deletions
weixin-java-cp/APPROVAL_WORKFLOW_GUIDE.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,141 @@ | ||
| # WeChat Enterprise Workflow Approval Guide | ||
| # 企业微信流程审批功能使用指南 | ||
|
|
||
| ## Overview / 概述 | ||
|
|
||
| WxJava SDK provides comprehensive support for WeChat Enterprise workflow approval (企业微信流程审批), including both traditional OA approval and the approval process engine. | ||
|
|
||
| WxJava SDK 提供全面的企业微信流程审批支持,包括传统OA审批和审批流程引擎。 | ||
|
|
||
| ## Current Implementation Status / 当前实现状态 | ||
|
|
||
| ### ✅ Fully Implemented APIs / 已完整实现的API | ||
|
|
||
| 1. **Submit Approval Application / 提交审批申请** | ||
| - Endpoint: `/cgi-bin/oa/applyevent` | ||
| - Documentation: [91853](https://work.weixin.qq.com/api/doc/90000/90135/91853) | ||
| - Implementation: `WxCpOaService.apply(WxCpOaApplyEventRequest)` | ||
|
|
||
| 2. **Get Approval Details / 获取审批申请详情** | ||
| - Endpoint: `/cgi-bin/oa/getapprovaldetail` | ||
| - Implementation: `WxCpOaService.getApprovalDetail(String spNo)` | ||
|
|
||
| 3. **Batch Get Approval Numbers / 批量获取审批单号** | ||
| - Endpoint: `/cgi-bin/oa/getapprovalinfo` | ||
| - Implementation: `WxCpOaService.getApprovalInfo(...)` | ||
|
|
||
| 4. **Approval Process Engine / 审批流程引擎** | ||
| - Endpoint: `/cgi-bin/corp/getopenapprovaldata` | ||
| - Implementation: `WxCpOaAgentService.getOpenApprovalData(String thirdNo)` | ||
|
|
||
| 5. **Template Management / 模板管理** | ||
| - Create: `WxCpOaService.createOaApprovalTemplate(...)` | ||
| - Update: `WxCpOaService.updateOaApprovalTemplate(...)` | ||
| - Get Details: `WxCpOaService.getTemplateDetail(...)` | ||
|
|
||
| ## Usage Examples / 使用示例 | ||
|
|
||
| ### 1. Submit Approval Application / 提交审批申请 | ||
|
|
||
| ```java | ||
| // Create approval request | ||
| WxCpOaApplyEventRequest request = new WxCpOaApplyEventRequest() | ||
| .setCreatorUserId("userId") | ||
| .setTemplateId("templateId") | ||
| .setUseTemplateApprover(0) | ||
| .setApprovers(Arrays.asList( | ||
| new WxCpOaApplyEventRequest.Approver() | ||
| .setAttr(2) | ||
| .setUserIds(new String[]{"approver1", "approver2"}) | ||
| )) | ||
| .setNotifiers(new String[]{"notifier1", "notifier2"}) | ||
| .setNotifyType(1) | ||
| .setApplyData(new WxCpOaApplyEventRequest.ApplyData() | ||
| .setContents(Arrays.asList( | ||
| new ApplyDataContent() | ||
| .setControl("Text") | ||
| .setId("Text-1234567890") | ||
| .setValue(new ContentValue().setText("Approval content")) | ||
| )) | ||
| ); | ||
|
|
||
| // Submit approval | ||
| String spNo = wxCpService.getOaService().apply(request); | ||
| ``` | ||
|
|
||
| ### 2. Get Approval Details / 获取审批详情 | ||
|
|
||
| ```java | ||
| // Get approval details by approval number | ||
| WxCpApprovalDetailResult result = wxCpService.getOaService() | ||
| .getApprovalDetail("approval_number"); | ||
|
|
||
| WxCpApprovalDetailResult.WxCpApprovalDetail detail = result.getInfo(); | ||
| System.out.println("Approval Status: " + detail.getSpStatus()); | ||
| System.out.println("Approval Name: " + detail.getSpName()); | ||
| ``` | ||
|
|
||
| ### 3. Batch Get Approval Information / 批量获取审批信息 | ||
|
|
||
| ```java | ||
| // Get approval info with filters | ||
| Date startTime = new Date(System.currentTimeMillis() - 7 * 24 * 60 * 60 * 1000); | ||
| Date endTime = new Date(); | ||
|
|
||
| WxCpApprovalInfo approvalInfo = wxCpService.getOaService() | ||
| .getApprovalInfo(startTime, endTime, "0", 100, null); | ||
|
|
||
| List<String> spNumbers = approvalInfo.getSpNoList(); | ||
| ``` | ||
|
|
||
| ### 4. Third-Party Application Support / 第三方应用支持 | ||
|
|
||
| ```java | ||
| // For third-party applications | ||
| WxCpTpOAService tpOaService = wxCpTpService.getOaService(); | ||
|
|
||
| // Submit approval for specific corp | ||
| String spNo = tpOaService.apply(request, "corpId"); | ||
|
|
||
| // Get approval details for specific corp | ||
| WxCpApprovalDetailResult detail = tpOaService.getApprovalDetail("spNo", "corpId"); | ||
| ``` | ||
|
|
||
| ## Multi-Account Configuration / 多账号配置支持 | ||
|
|
||
| WxJava supports multi-account configurations for enterprise scenarios: | ||
|
|
||
| ```java | ||
| // Spring Boot configuration example | ||
| @Autowired | ||
| private WxCpMultiServices wxCpMultiServices; | ||
|
|
||
| // Get service for specific corp | ||
| WxCpService wxCpService = wxCpMultiServices.getWxCpService("corpId"); | ||
| WxCpOaService oaService = wxCpService.getOaService(); | ||
| ``` | ||
|
|
||
| ## Available Data Models / 可用数据模型 | ||
|
|
||
| - `WxCpOaApplyEventRequest` - Approval application request | ||
| - `WxCpApprovalDetailResult` - Approval details response | ||
| - `WxCpApprovalInfo` - Batch approval information | ||
| - `WxCpXmlApprovalInfo` - XML approval message handling | ||
| - `WxCpOaApprovalTemplate` - Approval template management | ||
|
|
||
| ## Documentation References / 文档参考 | ||
|
|
||
| - [Submit Approval Application (91853)](https://work.weixin.qq.com/api/doc/90000/90135/91853) | ||
| - [Get Approval Details (91983)](https://work.weixin.qq.com/api/doc/90000/90135/91983) | ||
| - [Batch Get Approval Numbers (91816)](https://work.weixin.qq.com/api/doc/90000/90135/91816) | ||
| - [Approval Process Engine (90269)](https://developer.work.weixin.qq.com/document/path/90269) | ||
|
|
||
| ## Conclusion / 结论 | ||
|
|
||
| WxJava already provides comprehensive support for WeChat Enterprise workflow approval. The "new version" (新版) approval functionality referenced in issue requests is **already fully implemented** and available for use. | ||
|
|
||
| WxJava 已经提供了企业微信流程审批的全面支持。问题中提到的"新版"流程审批功能**已经完全实现**并可使用。 | ||
|
|
||
| For questions about specific usage, please refer to the test cases in `WxCpOaServiceImplTest` and the comprehensive API documentation. | ||
|
|
||
| 有关具体使用问题,请参考 `WxCpOaServiceImplTest` 中的测试用例和全面的API文档。 |
189 changes: 189 additions & 0 deletions
weixin-java-cp/src/test/java/me/chanjar/weixin/cp/demo/WxCpApprovalWorkflowDemo.java
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,189 @@ | ||
| package me.chanjar.weixin.cp.demo; | ||
|
|
||
| import me.chanjar.weixin.cp.api.WxCpService; | ||
| import me.chanjar.weixin.cp.bean.oa.WxCpApprovalDetailResult; | ||
| import me.chanjar.weixin.cp.bean.oa.WxCpApprovalInfo; | ||
| import me.chanjar.weixin.cp.bean.oa.WxCpOaApplyEventRequest; | ||
| import me.chanjar.weixin.cp.bean.oa.applydata.ApplyDataContent; | ||
| import me.chanjar.weixin.cp.bean.oa.applydata.ContentValue; | ||
|
|
||
| import java.util.Arrays; | ||
| import java.util.Date; | ||
|
|
||
| /** | ||
| * 企业微信流程审批功能演示代码 | ||
| * WeChat Enterprise Workflow Approval Demo | ||
| * | ||
| * 演示如何使用WxJava SDK中已实现的完整审批流程功能 | ||
| * Demonstrates how to use the comprehensive approval workflow features already implemented in WxJava SDK | ||
| * | ||
| * 文档参考 Documentation Reference: https://work.weixin.qq.com/api/doc/90000/90135/91853 | ||
| */ | ||
| public class WxCpApprovalWorkflowDemo { | ||
|
|
||
| private WxCpService wxCpService; | ||
|
|
||
| public WxCpApprovalWorkflowDemo(WxCpService wxCpService) { | ||
| this.wxCpService = wxCpService; | ||
| } | ||
|
|
||
| /** | ||
| * 示例1: 提交审批申请 | ||
| * Example 1: Submit Approval Application | ||
| * API: /cgi-bin/oa/applyevent (Document 91853) | ||
| */ | ||
| public String submitApprovalApplication() throws Exception { | ||
| // 构建审批申请请求 | ||
| WxCpOaApplyEventRequest request = new WxCpOaApplyEventRequest() | ||
| .setCreatorUserId("creator_user_id") // 申请人userid | ||
| .setTemplateId("3Tka1eD6v6JfzhDMqPd3aMkFdxqtJMc2ZRioUBGCNS") // 模板id | ||
| .setUseTemplateApprover(0) // 不使用模板中的审批流 | ||
| .setApprovers(Arrays.asList( | ||
| new WxCpOaApplyEventRequest.Approver() | ||
| .setAttr(2) // 审批类型: 或签 | ||
| .setUserIds(new String[]{"approver1", "approver2"}) | ||
| )) | ||
| .setNotifiers(new String[]{"notifier1", "notifier2"}) // 抄送人 | ||
| .setNotifyType(1) // 抄送方式: 提单时抄送 | ||
| .setApplyData(new WxCpOaApplyEventRequest.ApplyData() | ||
| .setContents(Arrays.asList( | ||
| // 文本控件 | ||
| new ApplyDataContent() | ||
| .setControl("Text") | ||
| .setId("Text-1234567890") | ||
| .setValue(new ContentValue().setText("这是一个审批申请的文本内容")), | ||
|
|
||
| // 数字控件 | ||
| new ApplyDataContent() | ||
| .setControl("Number") | ||
| .setId("Number-1234567890") | ||
| .setValue(new ContentValue().setNewNumber("1000")), | ||
|
|
||
| // 金额控件 | ||
| new ApplyDataContent() | ||
| .setControl("Money") | ||
| .setId("Money-1234567890") | ||
| .setValue(new ContentValue().setNewMoney("10000")) | ||
| )) | ||
| ); | ||
|
|
||
| // 提交审批申请 | ||
| String spNo = wxCpService.getOaService().apply(request); | ||
| System.out.println("审批申请提交成功,审批单号: " + spNo); | ||
|
|
||
| return spNo; | ||
| } | ||
|
|
||
| /** | ||
| * 示例2: 获取审批申请详情 | ||
| * Example 2: Get Approval Application Details | ||
| * API: /cgi-bin/oa/getapprovaldetail | ||
| */ | ||
| public void getApprovalDetails(String spNo) throws Exception { | ||
| WxCpApprovalDetailResult result = wxCpService.getOaService().getApprovalDetail(spNo); | ||
|
|
||
| WxCpApprovalDetailResult.WxCpApprovalDetail detail = result.getInfo(); | ||
|
|
||
| System.out.println("审批单号: " + detail.getSpNo()); | ||
| System.out.println("审批名称: " + detail.getSpName()); | ||
| System.out.println("审批状态: " + detail.getSpStatus().getCode()); | ||
| System.out.println("申请人: " + detail.getApplyer().getUserId()); | ||
| System.out.println("申请时间: " + detail.getApplyTime()); | ||
|
|
||
| // 打印审批记录 | ||
| if (detail.getSpRecord() != null) { | ||
| detail.getSpRecord().forEach(record -> { | ||
| System.out.println("审批节点状态: " + record.getSpStatus()); | ||
| System.out.println("审批人: " + record.getDetails()); | ||
| }); | ||
| } | ||
| } | ||
|
|
||
| /** | ||
| * 示例3: 批量获取审批单号 | ||
| * Example 3: Batch Get Approval Numbers | ||
| * API: /cgi-bin/oa/getapprovalinfo | ||
| */ | ||
| public void batchGetApprovalInfo() throws Exception { | ||
| // 获取最近7天的审批单 | ||
| Date startTime = new Date(System.currentTimeMillis() - 7 * 24 * 60 * 60 * 1000L); | ||
| Date endTime = new Date(); | ||
|
|
||
| WxCpApprovalInfo approvalInfo = wxCpService.getOaService() | ||
| .getApprovalInfo(startTime, endTime, "0", 100, null); | ||
|
|
||
| System.out.println("获取到的审批单数量: " + approvalInfo.getCount()); | ||
|
|
||
| // 遍历审批单号 | ||
| if (approvalInfo.getSpNoList() != null) { | ||
| approvalInfo.getSpNoList().forEach(spNo -> { | ||
| System.out.println("审批单号: " + spNo); | ||
| // 可以进一步调用 getApprovalDetails 获取详情 | ||
| }); | ||
| } | ||
| } | ||
|
|
||
| /** | ||
| * 示例4: 模板管理 | ||
| * Example 4: Template Management | ||
| */ | ||
| public void templateManagement() throws Exception { | ||
| // 获取模板详情 | ||
| String templateId = "3Tka1eD6v6JfzhDMqPd3aMkFdxqtJMc2ZRioUBGCNS"; | ||
| var templateResult = wxCpService.getOaService().getTemplateDetail(templateId); | ||
|
|
||
| System.out.println("模板名称: " + templateResult.getTemplateNames()); | ||
| System.out.println("模板内容: " + templateResult.getTemplateContent()); | ||
| } | ||
|
|
||
| /** | ||
| * 完整的审批流程演示 | ||
| * Complete Approval Workflow Demo | ||
| */ | ||
| public void completeWorkflowDemo() { | ||
| try { | ||
| System.out.println("=== 企业微信流程审批完整演示 ==="); | ||
|
|
||
| // 1. 提交审批申请 | ||
| System.out.println("\n1. 提交审批申请..."); | ||
| String spNo = submitApprovalApplication(); | ||
|
|
||
| // 2. 获取审批详情 | ||
| System.out.println("\n2. 获取审批详情..."); | ||
| getApprovalDetails(spNo); | ||
|
|
||
| // 3. 批量获取审批信息 | ||
| System.out.println("\n3. 批量获取审批信息..."); | ||
| batchGetApprovalInfo(); | ||
|
|
||
| // 4. 模板管理 | ||
| System.out.println("\n4. 模板管理..."); | ||
| templateManagement(); | ||
|
|
||
| System.out.println("\n=== 演示完成 ==="); | ||
| System.out.println("WxJava SDK 已经完整支持企业微信流程审批功能!"); | ||
|
|
||
| } catch (Exception e) { | ||
| System.err.println("演示过程中发生错误: " + e.getMessage()); | ||
| e.printStackTrace(); | ||
| } | ||
| } | ||
|
|
||
| public static void main(String[] args) { | ||
| // 注意: 这里需要配置真实的企业微信服务 | ||
| // Note: You need to configure real WeChat Enterprise service here | ||
|
|
||
| System.out.println("企业微信流程审批功能演示"); | ||
| System.out.println("该演示代码展示了WxJava SDK中已经完整实现的审批流程功能"); | ||
| System.out.println("包括文档91853中描述的所有核心功能"); | ||
| System.out.println(""); | ||
| System.out.println("主要功能:"); | ||
| System.out.println("- 提交审批申请 (/cgi-bin/oa/applyevent)"); | ||
| System.out.println("- 获取审批详情 (/cgi-bin/oa/getapprovaldetail)"); | ||
| System.out.println("- 批量获取审批单号 (/cgi-bin/oa/getapprovalinfo)"); | ||
| System.out.println("- 模板管理功能"); | ||
| System.out.println("- 审批流程引擎支持"); | ||
| System.out.println(""); | ||
| System.out.println("如需运行演示,请配置正确的企业微信服务参数。"); | ||
| } | ||
| } |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.