Add comprehensive documentation for existing WeChat Enterprise workflow approval support

weixin-java-cp/APPROVAL_WORKFLOW_GUIDE.md

@@ -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文档。

weixin-java-cp/src/test/java/me/chanjar/weixin/cp/demo/WxCpApprovalWorkflowDemo.java

@@ -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("如需运行演示，请配置正确的企业微信服务参数。");
+    }
+}